[go: up one dir, main page]
 Back to top

Dataiku DSS API

Call paths

All calls in the DSS public API are relative to the /public/api path on the DSS server.

For example, if your DSS server is available at http://mymachine:10000/, and you want to call the List projects API, you must make a GET request on http://mymachine:10000/public/api/projects/

Other notes

Many API calls may return contain additional attributes compared to the documentation. The stability of these additional attributes is not guaranteed. They may be modified or removed in future releases without notice.

All API calls will return the following two HTTP headers

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

Projects

Projects

List projects
GET/projects/{tags}

Lists the projects. Only the projects on which the API key has the READ_CONF privilege will be listed.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/tags
URI Parameters
HideShow
tags
string (optional) Default: true 

Comma separated list of tags. The query will only return projects having one of these tags

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "Hello, world!"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create project
POST/projects

Creates a new project

🔒 Required privileges : Admin

Example URI

POST /projects
Request
HideShow

A project key must match [A-Za-z_]*

Headers
Content-Type: application/json
Body
{
  "projectKey": "The project key of the new project",
  "name": "The name of the new project",
  "owner": "The login of the owner of the new project"
}
Response  200

Project

Get project metadata
GET/projects/{projectKey}/metadata

Retrieves metadata about this project.

🔒 Required privileges : ADMIN (on project)

Example URI

GET /projects/MYPROJECT/metadata
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "label" : "My first project",
    "description" : "This is a sample project summary",
    "shortDesc" : "sample project summary",
    /* It is advised to keep tags as short words */
    "tags" : [
        "my tag 1",
        "my tag 2",
        ...
    ],
    "custom" : {
        "kv" : {
            "as a user" : "I can write",
            "whatever" : [ "I", "want" , "here"]
        }
    }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Display name for this object"
    },
    "description": {
      "type": "string",
      "description": "Long description (Markdown) for this object"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this object"
    },
    "custom": {
      "type": "object",
      "properties": {},
      "description": "Custom opaque metadata"
    }
  }
}

Update project metadata
PUT/projects/{projectKey}/metadata

Updates metadata about this project. You should only set a metadata object that has been obtained through the corresponding GET call.

🔒 Required privileges : ADMIN (on project)

Example URI

PUT /projects/MYPROJECT/metadata
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "label" : "My first project",
    "description" : "This is a sample project summary",
    "shortDesc" : "sample project summary",
    /* It is advised to keep tags as short words */
    "tags" : [
        "my tag 1",
        "my tag 2",
        ...
    ],
    "custom" : {
        "kv" : {
            "as a user" : "I can write",
            "whatever" : [ "I", "want" , "here"]
        }
    }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Display name for this object"
    },
    "description": {
      "type": "string",
      "description": "Long description (Markdown) for this object"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this object"
    },
    "custom": {
      "type": "object",
      "properties": {},
      "description": "Custom opaque metadata"
    }
  }
}
Response  204

Get project permissions
GET/projects/{projectKey}/permissions

Retrieves access permissions for this project.

🔒 Required privileges : ADMIN (on project)

Example URI

GET /projects/MYPROJECT/permissions
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "owner": "Hello, world!",
  "permissions": [
    {
      "group": "Hello, world!",
      "type": "Hello, world!"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Login of the owner of the proejct"
    },
    "permissions": {
      "type": "array",
      "description": "List of group -> access level mapping"
    }
  }
}

Update project permissions
PUT/projects/{projectKey}/permissions

Updates access permissions for this project. You should only set a permissions object that has been obtained through the corresponding GET call.

🔒 Required privileges : ADMIN (on project)

Example URI

PUT /projects/MYPROJECT/permissions
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "owner": "Hello, world!",
  "permissions": [
    {
      "group": "Hello, world!",
      "type": "Hello, world!"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Login of the owner of the proejct"
    },
    "permissions": {
      "type": "array",
      "description": "List of group -> access level mapping"
    }
  }
}
Response  204

Get project variables
GET/projects/{projectKey}/variables

Retrieves project-level variables for this project.

🔒 Required privileges : READ_CONF (on project)

Example URI

GET /projects/MYPROJECT/variables
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

Response  200
HideShow

“Local” variables are not kept when deploying a project to an automation node

Headers
Content-Type: application/json
Body
{
  "standard": {
    "k1": "v1",
    "k2": 14
  },
  "local": {}
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "standard": {
      "type": "object",
      "properties": {},
      "description": "Dictionary of \"regular\" variables for this project. Regular variables are transfered when deploying a project to the automation node"
    },
    "local": {
      "type": "object",
      "properties": {},
      "description": "Dictionary of \"local\" variables for this project. Local variables are not transfered when deploying a project to the automation node. Local variables override standard variables with the same name"
    }
  }
}

Update project variables
PUT/projects/{projectKey}/variables

Updates project-level variables for this project. You should only set a variables object that has been obtained through the corresponding GET call.

🔒 Required privileges : WRITE_CONF (on project)

Example URI

PUT /projects/MYPROJECT/variables
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

Request
HideShow

“Local” variables are not kept when deploying a project to an automation node

Headers
Content-Type: application/json
Body
{
  "standard": {
    "k1": "v1",
    "k2": 14
  },
  "local": {}
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "standard": {
      "type": "object",
      "properties": {},
      "description": "Dictionary of \"regular\" variables for this project. Regular variables are transfered when deploying a project to the automation node"
    },
    "local": {
      "type": "object",
      "properties": {},
      "description": "Dictionary of \"local\" variables for this project. Local variables are not transfered when deploying a project to the automation node. Local variables override standard variables with the same name"
    }
  }
}
Response  204

Delete project
DELETE/projects/{projectKey}

Permanently deletes a project and all its associated datasets, recipes, models, etc.

🔒 Required privileges : ADMIN (on this project)

Example URI

DELETE /projects/MYPROJECT
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project to delete

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

Response  204

Export project
GET/projects/{projectKey}/export{?exportUploads}{?exportManaged}{?exportAnalysisModels}{?exportSavedModels}

Exports a whole project configuration and (optionally) its associated data.

Only the content of Managed Filesystem datasets and uploaded datasets can be exported.

The returned zip archive can be used in DSS import feature.

🔒 Required privileges : ADMIN (on this project)

Example URI

GET /projects/MYPROJECT/export?exportUploads=?exportManaged=?exportAnalysisModels=?exportSavedModels=
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

exportUploads
boolean (optional) Default: true 
exportManaged
boolean (optional) Default: true 
exportAnalysisModels
boolean (optional) Default: true 
exportSavedModels
boolean (optional) Default: true 
Response  200
HideShow
Headers
Content-Type: application/zip

Push to Git remote
POST/projects/{projectKey}/actions/push-to-git-remote{?remote}

Pushes the content of a project to a previously-declared Git remote. The remote must have been added first in the “Changes” section of DSS.

DSS must be in “per-project Git” mode

🔒 Required privileges : ADMIN (on this project)

Example URI

POST /projects/MYPROJECT/actions/push-to-git-remote?remote=origin
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

NB The project key is usually different than the project displayed name.

The projectKey can be found with the list projects API call or in the URL when accessing DSS GUI.

remote
string (required) Example: origin

The remote name to push to

Response  204

Datasets

Datasets

List datasets
GET/projects/{projectKey}/datasets/{?tags}{?foreign}

Lists the datasets of a project.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/projectKey/datasets/?tags=tag1,tag2?foreign=true
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

foreign
boolean (optional) Default: false Example: true

If true, also lists the datasets from other projects that are exposed to the specified project

tags
string (optional) Example: tag1,tag2

Comma separated list of tags. The query will only return datasets having one of these tags

Response  200
HideShow

Returns an array of [Dataset] object. See GET Dataset for more information on the [Dataset] object

Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "PKEY1",
    "name": "dataset1",
    "type": "Filesystem",
    "params": {
      "connection": "filesystem_input",
      "path": "/src/dataset1"
    },
    "formatType": "csv",
    "formatParams": {
      "style": "EXCEL",
      "separator": "\t"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create dataset
POST/projects/{projectKey}/datasets

Creates a new dataset.

Important: most parameters and format parameters of datasets are not officially documented and may be modified in future recipes. It is recommended that you use the GET Dataset call to retrieve an existing dataset and modify it to suit your needs and create a new Dataset.

🔒 Required privileges : WRITE_CONF

Example URI

POST /projects/projectKey/datasets
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "PKEY1",
  "name": "dataset1",
  "type": "Filesystem",
  "params": {
    "connection": "filesystem_input",
    "path": "/src/dataset1"
  },
  "formatType": "csv",
  "formatParams": {
    "style": "EXCEL",
    "separator": "\t"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this dataset"
    },
    "name": {
      "type": "string",
      "description": "Unique name of this dataset in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the dataset"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the connection to the data. The available parameters depend on the dataset type"
    },
    "formatType": {
      "type": "string",
      "description": "For file-based datasets, the name of the format"
    },
    "formatParams": {
      "type": "object",
      "properties": {},
      "description": "For file-based datasets, the parameters of the format. The actual parameters depend on the format type"
    },
    "managed": {
      "type": "boolean",
      "description": "Whether this is a managed dataset. See [DSS documentation](http://doc.dataiku.com/dss/latest/concepts/#managed-and-external-datasets) for an explanation"
    },
    "schema": {
      "type": "object",
      "properties": {},
      "description": "Schema of this dataset"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this dataset"
    }
  }
}
Response  204

Dataset

To build a dataset see POST job

Get dataset settings
GET/projects/{projectKey}/datasets/{datasetName}

Retrieves a Dataset object.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/datasets/mydataset
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "PKEY1",
  "name": "dataset1",
  "type": "Filesystem",
  "params": {
    "connection": "filesystem_input",
    "path": "/src/dataset1"
  },
  "formatType": "csv",
  "formatParams": {
    "style": "EXCEL",
    "separator": "\t"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this dataset"
    },
    "name": {
      "type": "string",
      "description": "Unique name of this dataset in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the dataset"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the connection to the data. The available parameters depend on the dataset type"
    },
    "formatType": {
      "type": "string",
      "description": "For file-based datasets, the name of the format"
    },
    "formatParams": {
      "type": "object",
      "properties": {},
      "description": "For file-based datasets, the parameters of the format. The actual parameters depend on the format type"
    },
    "managed": {
      "type": "boolean",
      "description": "Whether this is a managed dataset. See [DSS documentation](http://doc.dataiku.com/dss/latest/concepts/#managed-and-external-datasets) for an explanation"
    },
    "schema": {
      "type": "object",
      "properties": {},
      "description": "Schema of this dataset"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this dataset"
    }
  }
}

Update dataset settings
PUT/projects/{projectKey}/datasets/{datasetName}

Updates the settings of a Dataset.

The Dataset object given as parameter in of a PUT call MUST have been previously obtained from a GET dataset call at the same URL.

The object obtained with the GET method may contain undocumented attributes. You should not modify them as it could create an invalid state and thoses attributes may be removed in future releases without notice.

🔒 Required privileges : WRITE_CONF

Example URI

PUT /projects/MYPROJECT/datasets/mydataset
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "projectKey" : "PKEY1",
    "name" : "dataset1",
    "type" : "Filesystem",
    "params" : {
        "connection" : "filesystem_input",
        "path" : "/src/dataset1"
    },
    "formatType" : "csv",
    "formatParams" : {
        "style" : "EXCEL",
        "separator" : "\t"
    }
    ...
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this dataset"
    },
    "name": {
      "type": "string",
      "description": "Unique name of this dataset in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the dataset"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the connection to the data. The available parameters depend on the dataset type"
    },
    "formatType": {
      "type": "string",
      "description": "For file-based datasets, the name of the format"
    },
    "formatParams": {
      "type": "object",
      "properties": {},
      "description": "For file-based datasets, the parameters of the format. The actual parameters depend on the format type"
    },
    "managed": {
      "type": "boolean",
      "description": "Whether this is a managed dataset. See [DSS documentation](http://doc.dataiku.com/dss/latest/concepts/#managed-and-external-datasets) for an explanation"
    },
    "schema": {
      "type": "object",
      "properties": {},
      "description": "Schema of this dataset"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this dataset"
    }
  }
}
Response  204

Delete dataset
DELETE/projects/{projectKey}/datasets/{datasetName}{?dropData}

Deletes a dataset.

WARNING : Deleting a dataset will trigger the deletion of all associated analyses and recipes.

🔒 Required privileges : WRITE_CONF, WRITE_DATA

Example URI

DELETE /projects/MYPROJECT/datasets/mydataset?dropData=false
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

dropData
boolean (optional) Default: false Example: false
Response  204

Dataset metadata

Get metadata
GET/projects/{projectKey}/datasets/{datasetName}/metadata

Retrieves metadata about this dataset.

🔒 Required privileges : READ_METADATA on Dataset

Example URI

GET /projects/MYPROJECT/datasets/mydataset/metadata
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "label": "dataset_name",
  "tags": [
    "tag1",
    "tag2"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Display name for this object"
    },
    "description": {
      "type": "string",
      "description": "Long description (Markdown) for this object"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this object"
    },
    "custom": {
      "type": "object",
      "properties": {},
      "description": "Custom opaque metadata"
    }
  }
}

Sets metadata
PUT/projects/{projectKey}/datasets/{datasetName}/metadata

Writes metadata about this dataset. You should only set a metadata object that has been obtained through the corresponding GET call.

🔒 Required privileges : WRITE_METADATA on Dataset

Example URI

PUT /projects/MYPROJECT/datasets/mydataset/metadata
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "label": "dataset_name",
  "tags": [
    "tag1",
    "tag2"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Display name for this object"
    },
    "description": {
      "type": "string",
      "description": "Long description (Markdown) for this object"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this object"
    },
    "custom": {
      "type": "object",
      "properties": {},
      "description": "Custom opaque metadata"
    }
  }
}
Response  200

Dataset schema

Get schema
GET/projects/{projectKey}/datasets/{datasetName}/schema

Retrieves the schema of the specified dataset. The dataset’s schema is the list of its columns with their types.

🔒 Required privileges : READ_SCHEMA on Dataset

Example URI

GET /projects/projectKey/datasets/datasetName/schema
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

datasetName
string (required) 

the name of a dataset

Response  200
HideShow

The Schema object has one attribute: columns (an array of SchemaColumn) - columns array[Column]

Each SchemaColumn has a name and a type:

  • name string

  • type string

  • maxLength int : for string type only, -1 means no maximum length

Existing types are:

  • string

  • boolean

  • tinyint, smallint, int, bigint

  • float, double

  • date

  • array, map, object

  • geopoint, geometry

Headers
Content-Type: application/json
Body
{
    columns: [
        {"name": "Column1", type: "string", maxLength: -1},
        {"name": "Column2", type: "bigint"},
    ]
}

Set schema
PUT/projects/{projectKey}/datasets/{datasetName}/schema

The Schema object given as parameter in of a PUT call MUST have been previously obtained from a GET schema call at the same URL.

The object with the GET method may contain undocumented attributes. You should not modify them as it could create an invalid state and thoses attributes may be removed in future releases without notice.

🔒 Required privileges : WRITE_SCHEMA

Example URI

PUT /projects/projectKey/datasets/datasetName/schema
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

datasetName
string (required) 

the name of a dataset

Request
HideShow

The Schema object has one attribute: columns (an array of SchemaColumn) - columns array[Column]

Each SchemaColumn has a name and a type:

  • name string

  • type string

  • maxLength int : for string type only, -1 means no maximum length

Existing types are:

  • string

  • boolean

  • tinyint, smallint, int, bigint

  • float, double

  • date

  • array, map, object

  • geopoint, geometry

Headers
Content-Type: application/json
Body
{
    columns: [
        {"name": "Column1", type: "string", maxLength: -1},
        {"name": "Column2", type: "bigint"},
    ]
}
Response  204

Dataset data

Get data
GET/projects/{projectKey}/datasets/{datasetName}/data{?format}{?formatParams}{?columns}{?partitions}{?filter}{?sampling}

Streams the content of a dataset.

🔒 Required privileges : READ_DATA on Dataset

Example URI

GET /projects/MYPROJECT/datasets/mydataset/data?format=json?formatParams=?columns=mycol1,mycol2?partitions=2015-07-07?filter=mycol1 > 0 && mycol3 > 0?sampling=
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

format
string (optional) Example: json

Output format name. Supported formats are : “json”, “tsv-excel-header” (tab-separated with header) and “tsv-excel-noheader” (tab-separated without header)

formatParams
string (optional) 

additional parameters for the chosen format, as a json string

columns
string (optional) Example: mycol1,mycol2

List of requested columns, as a comma-separated list

sampling
string (optional) 

definition of a sampling to use when retrieving the data. By default, no sampling (returns all data)

partitions
string (optional) Example: 2015-07-07

Partition list specification

filter
string (optional) Example: mycol1 > 0 && mycol3 > 0

Formula to select only a subset of rows based on a boolean expression

Response  200
HideShow

The Content-Type and the content of the request may change according to the requested format.

The default (json) output will produce an array of arrays representing the data:

Body
[
    [ "a", "1"],
    [ "b", "2"],
    ...
]

Get data - alternative version
POST/projects/{projectKey}/datasets/{datasetName}/data

Streams the content of a dataset.

This is a variant of the previous method using POST to post large and complex requests

🔒 Required privileges : READ_DATA

Example URI

POST /projects/MYPROJECT/datasets/mydataset/data
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "columns": [
    "Hello, world!"
  ],
  "partitions": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "columns": {
      "type": "array",
      "description": "If null, all columns are returned"
    },
    "partitions": {
      "type": "string",
      "description": "Partition spec"
    }
  }
}
Response  200
HideShow

The Content-Type and the content of the request may change according to the requested format.

The default (json) output will produce an array of arrays representing the data:

Body
[
    [ "a", "1"],
    [ "b", "2"],
    ...
]

Clear data
DELETE/projects/{projectKey}/datasets/{datasetName}/data/{?partitions}

Clears the data contained in the dataset; the dataset itself is not deleted.

If a list of partition identifiers is specified, only the corresponding partitions are cleared.

🔒 Required privileges : WRITE_DATA

Example URI

DELETE /projects/MYPROJECT/datasets/mydataset/data/?partitions=NP
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

partitions
string (optional) Example: NP

List of partitions to clear, as a partitions spec

Response  204

Dataset status

List partitions
GET/projects/{projectKey}/datasets/{datasetName}/partitions

Lists the partitions of the specified dataset. If the dataset is not partitioned, returns ["NP"]

🔒 Required privileges : READ_DATA

Example URI

GET /projects/MYPROJECT/datasets/mydataset/partitions
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

Response  200
HideShow
Body
[
    "2015-01-01",
    "2015-01-02",
    ...
]

Get last metric values
GET/projects/{projectKey}/datasets/{datasetName}/metrics/last/{?partition}

Retrieve the last values of all metrics on a given dataset (or dataset partition)

🔒 Required privileges : READ_METADATA

Example URI

GET /projects/MYPROJECT/datasets/mydataset/metrics/last/?partition=2015-02-03
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

partition
string (required) Example: 2015-02-03

partition id, if the dataset is partitioned. In that case, use ALL to obtain metrics on the whole dataset

Response  200
HideShow

For each metric, a complex object is returned

Body
{
  "metrics": [
    {
      "metric": {
        "dataType": "BIGINT",
        "type": "basic",
        "id": "basic:SIZE",
        "metricType": "SIZE"
      },
      "meta": {
        "fullName": "Size",
        "name": "Size",
        "format": "filesize"
      },
      "partitionsWithValue": [
        "2015-01-01"
      ],
      "lastValues": [
        {
          "dataType": "BIGINT",
          "partition": "2015-01-01",
          "computed": 1461659714763,
          "value": "33871"
        }
      ]
    }
  ]
}

Get single metric history
GET/projects/{projectKey}/datasets/{datasetName}/metrics/history/{?partition}{?metricLookup}

Retrieve the history values of a single metric on a given dataset (or dataset partition)

🔒 Required privileges : READ_METADATA

Example URI

GET /projects/MYPROJECT/datasets/mydataset/metrics/history/?partition=2015-02-03?metricLookup=records:COUNT_RECORDS
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

partition
string (required) Example: 2015-02-03

partition id, if the dataset is partitioned. In that case, use ALL to obtain metrics on the whole dataset

metricLookup
string (required) Example: records:COUNT_RECORDS

id of the metric to get values for

Response  200
HideShow
Body
{
  "lastValue": {
    "partition": "2015-01-01",
    "value": 33871,
    "time": 1461659714763
  },
  "from": 1458805030618,
  "to": 1461659714763,
  "dataType": "BIGINT",
  "metric": {
    "dataType": "BIGINT",
    "type": "basic",
    "id": "basic:SIZE",
    "metricType": "SIZE"
  },
  "metricId": "basic:SIZE",
  "values": [
    {
      "partition": "2015-01-01",
      "value": 33871,
      "time": 1458805030618
    },
    {
      "partition": "2015-01-01",
      "value": 33871,
      "time": 1458805030814
    },
    {
      "partition": "2015-01-01",
      "value": 33871,
      "time": 1458805334673
    }
  ],
  "valueType": "BIGINT"
}

Actions on dataset

Synchronize Hive metastore
POST/projects/{projectKey}/datasets/{datasetName}/actions/synchronizeHiveMetastore

Synchronizes the Hive table associated with the dataset, that is, updates or create the table’s so that it corresponds to the dataset’s schema.

Only makes sense on HDFS datasets

🔒 Required privileges : READ_DATA

Example URI

POST /projects/MYPROJECT/datasets/mydataset/actions/synchronizeHiveMetastore
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

Response  204

Update from Hive metastore
POST/projects/{projectKey}/datasets/{datasetName}/actions/updateFromHive

Updates the dataset from the table it’s associated with in Hive. This can change the dataset’s path, schema, partitioning scheme and format.

Only makes sense on HDFS datasets

🔒 Required privileges : READ_DATA

Example URI

POST /projects/MYPROJECT/datasets/mydataset/actions/updateFromHive
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

Response  204

Compute metrics
POST/projects/{projectKey}/datasets/{datasetName}/actions/computeMetrics/{?partitions}

Compute the metrics defined on the dataset. If the body is empty, the probes configured on the dataset are used; otherwise, the probes definition passed in the body are used.

🔒 Required privileges : ADMIN

Example URI

POST /projects/MYPROJECT/datasets/mydataset/actions/computeMetrics/?partitions=
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

partitions
string (optional) 

List of partitions to compute metrics for, as a partitions spec

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "engineConfig": {
    "hive": {
      "active": true,
      "extraConf": [
        {
          "key": "...",
          "value": "..."
        }
      ]
    }
  },
  "probes": [
    {
      "type": "basic",
      "configuration": {
        "enable": "true"
      }
    },
    {
      "type": "records",
      "configuration": {
        "countRecords": "true"
      }
    }
  ]
}
Response  200
HideShow
Body
{
  "result": {
    "computed": [
      {
        "metricId": "basic:SIZE",
        "value": "21568",
        "dataType": "BIGINT"
      },
      {
        "metricId": "COUNT_FILES",
        "value": "3",
        "dataType": "BIGINT"
      }
    ]
  }
}

Run checks
POST/projects/{projectKey}/datasets/{datasetName}/actions/runChecks/{?partitions}

Run the checks defined on the dataset. If the body is empty, the checks configured on the dataset are used; otherwise, the checks definition passed in the body are used.

🔒 Required privileges : ADMIN

Example URI

POST /projects/MYPROJECT/datasets/mydataset/actions/runChecks/?partitions=
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

datasetName
string (required) Example: mydataset

the name of a dataset

partitions
string (optional) 

List of partitions to run checks on, as a partitions spec

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "checks": [
    {
      "type": "numericRange",
      "metricId": "basic:SIZE",
      "minimum": "20000",
      "minimumEnabled": true
    }
  ]
}
Response  200
HideShow
Body
{
  "result": {
    "results": [
      {
        "check": {
          "type": "numericRange",
          "metricId": "basic:SIZE",
          "minimum": "20000",
          "minimumEnabled": true
        },
        "value": {
          "outcome": "OK",
          "message": "all good"
        }
      }
    ]
  }
}

Managed Folders

Managed folders

List Managed folders
GET/projects/{projectKey}/managedfolders/

Lists the managed folders of a project.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/projectKey/managedfolders/
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

Response  200
HideShow

See GET managed folder for more information

Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "Hello, world!",
    "id": "Hello, world!",
    "name": "Hello, world!",
    "path": "Hello, world!",
    "tags": [
      "Hello, world!"
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create managed folder
POST/projects/{projectKey}/managedfolders

Create a new managed folder.

Important: it is recommended that you use the GET ManagedFolder call to retrieve an existing managed folder and modify it to suit your needs and create a new managed folder.

🔒 Required privileges : WRITE_CONF

Example URI

POST /projects/projectKey/managedfolders
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "Hello, world!",
  "id": "Hello, world!",
  "name": "Hello, world!",
  "path": "Hello, world!",
  "tags": [
    "Hello, world!"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this managed folder"
    },
    "id": {
      "type": "string",
      "description": "Unique identifier of this managed folder in its project"
    },
    "name": {
      "type": "string",
      "description": "Name of this managed folder in its project"
    },
    "path": {
      "type": "string",
      "description": "Path to the actual filesystem folder of this managed folder"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this managed folder"
    }
  }
}
Response  204

Managed folder

To create a managed folder see POST managedfolders

Get managed folder settings
GET/projects/{projectKey}/managedfolders/{folderId}

Retrieves a Managed Folder object

🔒 Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/managedfolders/b21ed09a
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the managed folder

folderId
string (required) Example: b21ed09a

the unique identifier of the managed folder

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "Hello, world!",
  "id": "Hello, world!",
  "name": "Hello, world!",
  "path": "Hello, world!",
  "tags": [
    "Hello, world!"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this managed folder"
    },
    "id": {
      "type": "string",
      "description": "Unique identifier of this managed folder in its project"
    },
    "name": {
      "type": "string",
      "description": "Name of this managed folder in its project"
    },
    "path": {
      "type": "string",
      "description": "Path to the actual filesystem folder of this managed folder"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this managed folder"
    }
  }
}

Update managed folder settings
PUT/projects/{projectKey}/managedfolders/{folderId}

Updates the settings of a Managed Folder.

The ManagedFolder object given as parameter in of a PUT call MUST have been previously obtained from a GET managedfolder call at the same URL.

The object obtained with the GET method may contain undocumented attributes. You should not modify them as it could create an invalid state and those attributes may be removed in future releases without notice.

Note : the path to the managed folder cannot be changed

🔒 Required privileges : WRITE_CONF

Example URI

PUT /projects/MYPROJECT/managedfolders/b21ed09a
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the managed folder

folderId
string (required) Example: b21ed09a

the unique identifier of the managed folder

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "Hello, world!",
  "id": "Hello, world!",
  "name": "Hello, world!",
  "path": "Hello, world!",
  "tags": [
    "Hello, world!"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this managed folder"
    },
    "id": {
      "type": "string",
      "description": "Unique identifier of this managed folder in its project"
    },
    "name": {
      "type": "string",
      "description": "Name of this managed folder in its project"
    },
    "path": {
      "type": "string",
      "description": "Path to the actual filesystem folder of this managed folder"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this managed folder"
    }
  }
}
Response  204

Delete managed folder
DELETE/projects/{projectKey}/managedfolders/{folderId}

Deletes a managed folder.

WARNING : Deleting a managed folder will trigger the deletion of all associated recipes.

🔒 Required privileges : WRITE_CONF

Example URI

DELETE /projects/MYPROJECT/managedfolders/b21ed09a
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the managed folder

folderId
string (required) Example: b21ed09a

the unique identifier of the managed folder

Response  204

Managed folder contents

List files in managed folder
GET/projects/{projectKey}/managedfolders/{folderId}/contents/

Lists the contents of a managed folder

🔒 Required privileges : READ_DATA

Example URI

GET /projects/MYPROJECT/managedfolders/b21ed09a/contents/
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the managed folder

folderId
string (required) Example: b21ed09a

the unique identifier of the managed folder

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "items": [
    {
      "path": "Hello, world!",
      "size": 1,
      "lastModified": 1
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "list of the files in the folder"
    }
  }
}

Download file from managed folder
GET/projects/{projectKey}/managedfolders/{folderId}/contents/{path}

Downloads the file with the specified relative path in the folder

🔒 Required privileges : READ_DATA

Example URI

GET /projects/MYPROJECT/managedfolders/b21ed09a/contents/path
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the managed folder

folderId
string (required) Example: b21ed09a

the unique identifier of the managed folder

path
string (required) 

the path to the file from the root of the folder

Response  200
HideShow
Body
The file's contents, as a stream

Delete a file from managed folder
DELETE/projects/{projectKey}/managedfolders/{folderId}/contents/{path}

Deletes the file with the specified relative path in the folder

🔒 Required privileges : WRITE_DATA

Example URI

DELETE /projects/MYPROJECT/managedfolders/b21ed09a/contents/path
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the managed folder

folderId
string (required) Example: b21ed09a

the unique identifier of the managed folder

path
string (required) 

the path to the file from the root of the folder

Response  204

Upload file to managed folder
POST/projects/{projectKey}/managedfolders/{folderId}/contents/

Uploads a file to the root of the folder. The file is sent as a multipart file.

🔒 Required privileges : WRITE_DATA

Example URI

POST /projects/MYPROJECT/managedfolders/b21ed09a/contents/
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the managed folder

folderId
string (required) Example: b21ed09a

the unique identifier of the managed folder

Response  204

Recipes

Recipes

List recipes
GET/projects/{projectKey}/recipes/

Lists the recipes of a project.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/projectKey/recipes/
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Response  200
HideShow

Returns an array of [Recipe] object. See GET Recipe for more information on the [Recipe] object

Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "PKEY1",
    "name": "recipe1",
    "type": "sync",
    "params": {},
    "inputs": {
      "main": {
        "items": [
          {
            "ref": "dataset1"
          },
          {
            "ref": "dataset2"
          }
        ]
      }
    },
    "outputs": {
      "main": {
        "items": [
          {
            "ref": "dataset3"
          }
        ]
      }
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create recipe
POST/projects/{projectKey}/recipes

Creates a new recipe.

Important: this call creates a recipe with the basic setup. To further configure it, use the GET Recipe and PUT Recipe calls.

🔒 Required privileges : WRITE_CONF

Example URI

POST /projects/projectKey/recipes
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "recipePrototype": {
    "projectKey": "PKEY1",
    "name": "recipe1",
    "type": "join",
    "params": {},
    "inputs": {
      "main": {
        "items": [
          {
            "ref": "inputDataset1"
          },
          {
            "ref": "inputDataset2"
          }
        ]
      }
    },
    "outputs": {
      "main": {
        "items": [
          {
            "ref": "outputDataset"
          }
        ]
      }
    }
  },
  "creationSettings": {}
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Desired name of the recipe in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the recipe"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the recipe. The exact parameters depend on the recipe type"
    },
    "inputs": {
      "type": "object",
      "properties": {},
      "description": "Inputs of the recipe."
    },
    "outputs": {
      "type": "object",
      "properties": {},
      "description": "Outputs of the recipe."
    }
  }
}
Response  200
HideShow

Returns the final unique name of the recipe

Headers
Content-Type: application/json
Body
{
    "name" : "recipe1",
}

Recipe

To build a recipe see POST recipes

Get recipe settings
GET/projects/{projectKey}/recipes/{recipeName}

Retrieves a Recipe object.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/recipes/myrecipe
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

recipeName
string (required) Example: myrecipe

the name of a recipe

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "recipe": {
    "projectKey": "PKEY1",
    "name": "recipe1",
    "type": "sync",
    "params": {}
  },
  "payload": "payload of the recipe"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recipe": {
      "type": "object",
      "properties": {
        "projectKey": {
          "type": "string",
          "description": "Project key of this recipe"
        },
        "name": {
          "type": "string",
          "description": "Unique name of this recipe in its project"
        },
        "type": {
          "type": "string",
          "description": "Type of the recipe"
        },
        "params": {
          "type": "object",
          "properties": {},
          "description": "Parameters of the recipe. The available parameters depend on the recipe type"
        },
        "inputs": {
          "type": "object",
          "properties": {},
          "description": "Inputs of the recipe."
        },
        "outputs": {
          "type": "object",
          "properties": {},
          "description": "Outputs of the recipe."
        }
      },
      "description": "Recipe definition"
    },
    "payload": {
      "type": "string",
      "description": "Payload of the recipe. The content depends on the recipe type"
    }
  }
}

Update recipe settings
PUT/projects/{projectKey}/recipes/{recipeName}

Updates the settings of a Recipe.

The RecipeAndPayload object given as parameter in of a PUT call MUST have been previously obtained from a GET recipe call at the same URL.

The object obtained with the GET method may contain undocumented attributes. You should not modify them as it could create an invalid state and thoses attributes may be removed in future releases without notice.

🔒 Required privileges : WRITE_CONF

Example URI

PUT /projects/MYPROJECT/recipes/myrecipe
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

recipeName
string (required) Example: myrecipe

the name of a recipe

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "recipe": {
    "projectKey": "PKEY1",
    "name": "recipe1",
    "type": "sync",
    "params": {}
  },
  "payload": "payload of the recipe"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this recipe"
    },
    "name": {
      "type": "string",
      "description": "Unique name of this recipe in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the recipe"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the recipe. The available parameters depend on the recipe type"
    },
    "inputs": {
      "type": "object",
      "properties": {},
      "description": "Inputs of the recipe."
    },
    "outputs": {
      "type": "object",
      "properties": {},
      "description": "Outputs of the recipe."
    }
  }
}
Response  204

Delete recipe
DELETE/projects/{projectKey}/recipes/{recipeName}

Deletes a recipe.

🔒 Required privileges : WRITE_CONF

Example URI

DELETE /projects/MYPROJECT/recipes/myrecipe
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

recipeName
string (required) Example: myrecipe

the name of a recipe

Response  204

Recipe metadata

Get metadata
GET/projects/{projectKey}/recipes/{recipeName}/metadata

Retrieves metadata about this recipe.

🔒 Required privileges : READ_METADATA on Project

Example URI

GET /projects/MYPROJECT/recipes/myrecipe/metadata
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

recipeName
string (required) Example: myrecipe

the name of a recipe

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "label": "recipe_name",
  "tags": [
    "tag1",
    "tag2"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Display name for this object"
    },
    "description": {
      "type": "string",
      "description": "Long description (Markdown) for this object"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this object"
    },
    "custom": {
      "type": "object",
      "properties": {},
      "description": "Custom opaque metadata"
    }
  }
}

Sets metadata
PUT/projects/{projectKey}/recipes/{recipeName}/metadata

Writes metadata about this recipe. You should only set a metadata object that has been obtained through the corresponding GET call.

🔒 Required privileges : WRITE_METADATA on Project

Example URI

PUT /projects/MYPROJECT/recipes/myrecipe/metadata
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

recipeName
string (required) Example: myrecipe

the name of a recipe

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "label": "recipe_name",
  "tags": [
    "tag1",
    "tag2"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "label": {
      "type": "string",
      "description": "Display name for this object"
    },
    "description": {
      "type": "string",
      "description": "Long description (Markdown) for this object"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this object"
    },
    "custom": {
      "type": "object",
      "properties": {},
      "description": "Custom opaque metadata"
    }
  }
}
Response  200

Jobs

Jobs

List latest jobs
GET/projects/{projectKey}/jobs{?limit}

Retrieves the list of the last jobs, as an array of JobSummary objects as defined in in the GET job call.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/jobs?limit=
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

limit
int (optional) Default: 0 

Maximum number of returned jobs, 0 for no limit.

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "Hello, world!",
    "jobId": "Hello, world!",
    "state": "Hello, world!"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Run job
POST/projects/{projectKey}/jobs

Start building a list of outputs.

A successful call means that the job was successfully initilized, not that it is completed. To follow the build progress use GET job.

Returns the complete job definition, including identifier of the job

🔒 Required privileges : RUN_JOBS

Example URI

POST /projects/MYPROJECT/jobs
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "outputs": [
    {
      "projectKey": "Hello, world!",
      "id": "Hello, world!",
      "partition": "Hello, world!"
    }
  ],
  "type": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "outputs": {
      "type": "array",
      "description": "Outputs to build for the job"
    },
    "type": {
      "type": "string",
      "description": "Type of job to build. One of RECURSIVE_BUILD, NON_RECURSIVE_FORCED_BUILD, RECURSIVE_FORCED_BUILD, RECURSIVE_MISSING_ONLY_BUILD"
    }
  },
  "required": [
    "outputs"
  ]
}
Response  200
HideShow
Body
{
  "projectKey": "Hello, world!",
  "id": "Hello, world!"
}
Schema
{
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string"
    },
    "id": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Job

Get job status
GET/projects/{projectKey}/jobs/{jobId}

Retrieves the job status as a JobSummary object summarising the state of a job and its activities.

A DSS job is a sequence of operations performed on datasets.

A job is divided into activities, each activity corresponds to a recipe run using a given set of partitions.

Example : running two recipes on 2 partitions will result in a job with 4 activities.

🔒 Required privileges : MONITOR_JOBS

Example URI

GET /projects/MYPROJECT/jobs/build_something_2016_02_10_21_23_34
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

jobId
string (required) Example: build_something_2016_02_10_21_23_34

the id of a job

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "baseStatus" : {
        /* Possible status are NOT_STARTED, RUNNING, FAILED, ABORTED and DONE */
        "status" : "DONE",
        "jobStartTime":1442418929502,
        "jobEndTime":1442418932140
    }
}

Abort
POST/projects/{projectKey}/jobs/{jobId}/abort

Requests the specified job to abort.

NB It may take some time for the job to actually stop, so when the servers answers this request, the job cannot be considered stopped.

🔒 Required privileges : RUN_JOBS

Example URI

POST /projects/MYPROJECT/jobs/build_something_2016_02_10_21_23_34/abort
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

jobId
string (required) Example: build_something_2016_02_10_21_23_34

the id of a job

Response  204

Job logs

Get job logs
GET/projects/{projectKey}/jobs/{jobId}/log{?activity}

Retrieves the logs content for a job or one of its activities (if specified).

🔒 Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/jobs/build_something_2016_02_10_21_23_34/log?activity=
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

jobId
string (required) Example: build_something_2016_02_10_21_23_34

the id of a job

activity
string (optional) 

Activity id from which to output the logs. If not provided return the global job logs.

Response  200
HideShow
Headers
Content-Type: text/plain

Long tasks

Tasks running in the instance

List tasks in progress
GET/futures/{?allUsers}{?withScenarios}

Retrieves the list of tasks running.

Example URI

GET /futures/?allUsers=false?withScenarios=false
URI Parameters
HideShow
allUsers
boolean (required) Example: false

whether to list tasks independently of who launched them or just the ones launched by the caller

withScenarios
boolean (required) Example: false

whether to include running scenarios in the list

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "jobId": "8sdf8ze",
    "hasResult": false,
    "aborted": false,
    "alive": false,
    "owner": "taskLauncher",
    "runningTime": 3135131,
    "progress": [
      {
        "name": "Doing something...",
        "unit": "SIZE",
        "target": 21513,
        "cur": 153
      }
    ]
  }
]

Get status of a running task
GET/futures/{jobId}{?peek}

Get the state of a running task.

Example URI

GET /futures/6qsaz81?peek=false
URI Parameters
HideShow
jobId
string (required) Example: 6qsaz81

the identifier of the task

peek
boolean (required) Example: false

whether to get the full status, with the result if it’s ready

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "jobId": "8sdf8ze",
  "hasResult": true,
  "result": {
    "any": "thing"
  },
  "aborted": false,
  "alive": false,
  "owner": "taskLauncher",
  "runningTime": 3135131,
  "progress": [
    {
      "name": "Doing something...",
      "unit": "SIZE",
      "target": 21513,
      "cur": 153
    }
  ]
}

Abort a task
GET/futures/{jobId}

Abort a running task

Example URI

GET /futures/6qsaz81
URI Parameters
HideShow
jobId
string (required) Example: 6qsaz81

the identifier of the task

Response  200

Scenarios

Scenarios

List scenarios of a project
GET/projects/{projectKey}/scenarios

Retrieves the list of scenarios, as an array of ScenarioWithStatus objects.

🔒 Required privileges : MONITOR_JOBS

Example URI

GET /projects/MYPROJECT/scenarios
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "Hello, world!",
    "running": true,
    "active": true
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create scenario
POST/projects/{projectKey}/scenarios

Creates a new scenario.

Important: most parameters and format parameters of datasets are not officially documented and may be modified in future releases.

🔒 Required privileges : WRITE_CONF

Example URI

POST /projects/MYPROJECT/scenarios
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "scenarioId",
  "active": true,
  "name": "scenarioName",
  "description": "",
  "type": "step_based",
  "params": {
    "steps": []
  },
  "triggers": [],
  "reporters": []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the scenario"
    },
    "name": {
      "type": "string",
      "description": "Name of the scenario"
    },
    "type": {
      "type": "string",
      "description": "Type of the scenario (step_based or custom_python)"
    },
    "active": {
      "type": "boolean",
      "description": "Is this scenario active, ie responding to its triggers?"
    },
    "description": {
      "type": "string",
      "description": "Description of the scenario"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the scenario. Depends on the type"
    },
    "triggers": {
      "type": "array",
      "description": "Trigger definitions of the scenario"
    },
    "reporters": {
      "type": "array",
      "description": "Reporter definitions of the scenario"
    }
  }
}
Response  204

Scenario

To build a scenario see POST scenarios

Get a scenario
GET/projects/{projectKey}/scenarios/{scenarioId}/

Retrieves a scenario, as a Scenario object.

🔒 Required privileges : MONITOR_JOBS

Example URI

GET /projects/MYPROJECT/scenarios/the_scenario/
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "scenarioId",
  "active": true,
  "name": "scenarioName",
  "description": "",
  "type": "step_based",
  "params": {
    "steps": []
  },
  "triggers": [],
  "reporters": []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the scenario"
    },
    "name": {
      "type": "string",
      "description": "Name of the scenario"
    },
    "type": {
      "type": "string",
      "description": "Type of the scenario (step_based or custom_python)"
    },
    "active": {
      "type": "boolean",
      "description": "Is this scenario active, ie responding to its triggers?"
    },
    "description": {
      "type": "string",
      "description": "Description of the scenario"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the scenario. Depends on the type"
    },
    "triggers": {
      "type": "array",
      "description": "Trigger definitions of the scenario"
    },
    "reporters": {
      "type": "array",
      "description": "Reporter definitions of the scenario"
    }
  }
}

Get the status of a scenario
GET/projects/{projectKey}/scenarios/{scenarioId}/light

Retrieves basic info and status for a scenario, as a ScenarioWithStatus object.

🔒 Required privileges : MONITOR_JOBS

Example URI

GET /projects/MYPROJECT/scenarios/the_scenario/light
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "Hello, world!",
  "running": true,
  "active": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the scenario"
    },
    "running": {
      "type": "boolean",
      "description": "Is this scenario currently running"
    },
    "active": {
      "type": "boolean",
      "description": "Is this scenario active, ie responding to its triggers?"
    }
  }
}

Get the payload of a scenario of a project
GET/projects/{projectKey}/scenarios/{scenarioId}/payload

Retrieves the “payload” of a scenario. This only makes sense for custom scenarios.

🔒 Required privileges : MONITOR_JOBS

Example URI

GET /projects/MYPROJECT/scenarios/the_scenario/payload
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "script": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "script": {
      "type": "string",
      "description": "Payload of the scenario"
    }
  }
}

Run a scenario
POST/projects/{projectKey}/scenarios/{scenarioId}/run

Start running a scenario.

A successful call means that the job was successfully initilized, not that it is completed. To follow the build progress use the list scenario calls.

This calls takes the scenario run parameters as a JSON object body

🔒 Required privileges : RUN_JOBS

Example URI

POST /projects/MYPROJECT/scenarios/the_scenario/run
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "triggerParam1": "value1",
  "triggerParam2": 49
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}
Response  200
HideShow
Body
Does not return any specific answer

Abort a scenario
POST/projects/{projectKey}/scenarios/{scenarioId}/abort

Abort a running scenario.

🔒 Required privileges : RUN_JOBS

Example URI

POST /projects/MYPROJECT/scenarios/the_scenario/abort
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

Request
HideShow
Headers
Content-Type: application/json
Body
Does not take any parameters
Response  200
HideShow
Body
Does not return any specific answer

Get last runs
GET/projects/{projectKey}/scenarios/{scenarioId}/get-last-runs/{?limit}

Retrieve the last runs of this scenario

🔒 Required privileges : RUN_JOBS

Example URI

GET /projects/MYPROJECT/scenarios/the_scenario/get-last-runs/?limit=200
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

limit
integer (optional) Example: 200

the number of runs to retrieve

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "runId": "2016-04-15-16-57-37-759",
    "start": 1460732257757,
    "end": 1460732282032,
    "scenario": {
      "name": "steps scenario",
      "automationLocal": false,
      "active": false,
      "type": "step_based",
      "id": "STEPS_SCENARIO",
      "projectKey": "PROJ",
      "description": "sqdsq"
    },
    "variables": {},
    "result": {
      "outcome": "SUCCESS",
      "type": "SCENARIO_DONE"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Get run from trigger run
GET/projects/scenarios/get-run-for-trigger/{?triggerId}{?triggerRunId}

Retrieve the run initiated by the given run of the trigger

🔒 Required privileges : RUN_JOBS

Example URI

GET /projects/scenarios/get-run-for-trigger/?triggerId=?triggerRunId=
URI Parameters
HideShow
triggerId
string (required) 

the unique identifier of the trigger

triggerRunId
string (required) 

the identifier of the run of the trigger

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "stepRuns": [
    {
      "end": 1460732282031,
      "start": 1460732257765,
      "step": {
        "type": "build_flowitem",
        "id": "build_0_true_d_train_set_prepared_split_year",
        "name": "build dataset train_set_prepared_split_year"
      },
      "result": {
        "start": 1460732257767,
        "end": 1460732282031,
        "outcome": "SUCCESS",
        "type": "STEP_DONE"
      },
      "additionalReportItems": [
        {
          "start": 1460732258480,
          "end": 1460732279882,
          "outcome": "SUCCESS",
          "target": {
            "type": "SAVED_MODEL",
            "projectKey": "SCEN",
            "modelId": "u4yPbO2B"
          },
          "warnings": {
            "totalCount": 0,
            "warnings": {}
          },
          "versionId": "1460732258821",
          "type": "BUILT_MODEL"
        },
        {
          "start": 1460732258001,
          "outcome": "SUCCESS",
          "end": 1460732282013,
          "target": {
            "type": "JOBS"
          },
          "jobId": "sched_build_2016-04-15T14-57-37.770",
          "type": "JOB_EXECUTED"
        }
      ],
      "runId": "2016-04-15-16-57-37-766"
    }
  ],
  "scenarioRun": {
    "runId": "2016-04-15-16-57-37-759"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Get details for a run
GET/projects/{projectKey}/scenarios/{scenarioId}/{runId}

Retrieve the details of a specific run of the scenario. The details include the outcomes of each step launched by the scenario, as well as their output if they offer one.

🔒 Required privileges : RUN_JOBS

Example URI

GET /projects/MYPROJECT/scenarios/the_scenario/runId
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

runId
string (required) 

identifier of the run

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "stepRuns": [
    {
      "end": 1460732282031,
      "start": 1460732257765,
      "step": {
        "type": "build_flowitem",
        "id": "build_0_true_d_train_set_prepared_split_year",
        "name": "build dataset train_set_prepared_split_year"
      },
      "result": {
        "start": 1460732257767,
        "end": 1460732282031,
        "outcome": "SUCCESS",
        "type": "STEP_DONE"
      },
      "additionalReportItems": [
        {
          "start": 1460732258480,
          "end": 1460732279882,
          "outcome": "SUCCESS",
          "target": {
            "type": "SAVED_MODEL",
            "projectKey": "SCEN",
            "modelId": "u4yPbO2B"
          },
          "warnings": {
            "totalCount": 0,
            "warnings": {}
          },
          "versionId": "1460732258821",
          "type": "BUILT_MODEL"
        },
        {
          "start": 1460732258001,
          "outcome": "SUCCESS",
          "end": 1460732282013,
          "target": {
            "type": "JOBS"
          },
          "jobId": "sched_build_2016-04-15T14-57-37.770",
          "type": "JOB_EXECUTED"
        }
      ],
      "runId": "2016-04-15-16-57-37-766"
    }
  ],
  "scenarioRun": {
    "runId": "2016-04-15-16-57-37-759"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Update scenario settings
PUT/projects/{projectKey}/scenarios/{scenarioId}

Updates the settings of a Scenario.

The [Scenario] object given as parameter in of a PUT call MUST have been previously obtained from a [GET scenario] call at the same URL.

The object obtained with the GET method may contain undocumented attributes. You should not modify them as it could create an invalid state and thoses attributes may be removed in future releases without notice.

🔒 Required privileges : WRITE_CONF

Example URI

PUT /projects/MYPROJECT/scenarios/the_scenario
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "projectKey" : "PKEY1",
    "name" : "scenarioId",
    "type" : "step_based",
    "params" : {
    }
    ...
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the scenario"
    },
    "name": {
      "type": "string",
      "description": "Name of the scenario"
    },
    "type": {
      "type": "string",
      "description": "Type of the scenario (step_based or custom_python)"
    },
    "active": {
      "type": "boolean",
      "description": "Is this scenario active, ie responding to its triggers?"
    },
    "description": {
      "type": "string",
      "description": "Description of the scenario"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the scenario. Depends on the type"
    },
    "triggers": {
      "type": "array",
      "description": "Trigger definitions of the scenario"
    },
    "reporters": {
      "type": "array",
      "description": "Reporter definitions of the scenario"
    }
  }
}
Response  204

Update basic scenario settings
PUT/projects/{projectKey}/scenarios/{scenarioId}/light

Updates the basic settings of a Scenario, given a BasicScenarioSettings object.

This is only useful to change the “active” status of a scenario

🔒 Required privileges : WRITE_CONF

Example URI

PUT /projects/MYPROJECT/scenarios/the_scenario/light
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "Hello, world!",
  "running": true,
  "active": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the scenario"
    },
    "running": {
      "type": "boolean",
      "description": "Is this scenario currently running"
    },
    "active": {
      "type": "boolean",
      "description": "Is this scenario active, ie responding to its triggers?"
    }
  }
}
Response  204

Update scenario payload
PUT/projects/{projectKey}/scenarios/{scenarioId}/payload

Updates the payload of a Scenario.

🔒 Required privileges : WRITE_CONF

Example URI

PUT /projects/MYPROJECT/scenarios/the_scenario/payload
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project of the scenario

scenarioId
string (required) Example: the_scenario

the id of the scenario

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "script": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "script": {
      "type": "string",
      "description": "Payload of the scenario"
    }
  }
}
Response  204

Meanings

Meanings

List meanings
GET/meanings/

Lists all user-defined meanings.

🔒 Required privileges : Admin

Example URI

GET /meanings/
Response  200
HideShow

See GET meaning for more information

Headers
Content-Type: application/json
Body
[
    {
        "id": "meaning1",
        "label": "Meaning 1",
        "type": "VALUES_MAPPING",
        "mappings": [
           {"from": "value_1", "to": "value_a"},
           {"from": "value_2", "to": "value_b"}
        ],
        "normalizationMode": "NORMALIZED",
        "description": "This is a sample meaning description.",
        "detectable": False 
    }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create meaning
POST/meanings

Creates a new meaning.

🔒 Required privileges : Admin

Example URI

POST /meanings
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "id": "meaning1",
    "label": "Meaning 1",
    "type": "VALUES_MAPPING",
    "mappings": [
       {"from": "value_1", "to": "value_a"},
       {"from": "value_2", "to": "value_b"}
    ],
    "normalizationMode": "NORMALIZED",
    "description": "This is a sample meaning description.",
    "detectable": False 
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the meaning"
    },
    "label": {
      "type": "string",
      "description": "Label of the meaning"
    },
    "type": {
      "type": "string",
      "description": "Type of the meaning. One of `DECLARATIVE`, `VALUES_LIST`, `VALUES_MAPPING`, `PATTERN`"
    },
    "description": {
      "type": "string",
      "description": "Description of the meaning"
    },
    "values": {
      "type": "array",
      "description": "For `VALUES_LIST` meanings, the valid values"
    },
    "mappings": {
      "type": "array",
      "description": "For `VALUES_MAPPING` meanings, the valid mappings"
    },
    "pattern": {
      "type": "array",
      "description": "For `PATTERN` meanings, the pattern"
    },
    "normalizationMode": {
      "type": "string",
      "description": "String normalization mode used to match values. One of `EXACT`, `LOWERCASE`, `NORMALIZED` (remove accents) for types `VALUES_LIST` and `VALUES_MAPPING`. One of `EXACT`, `LOWERCASE` for `PATTERN`"
    },
    "detectable": {
      "type": "boolean",
      "description": "Whether DSS should consider assigning the meaning to columns set to Auto-detect"
    }
  }
}
Response  204

Meaning

Get meaning definition
GET/meanings/{meaningId}

Retrieves a meaning object.

🔒 Required privileges : Admin

Example URI

GET /meanings/dept_code
URI Parameters
HideShow
meaningId
string (required) Example: dept_code

the ID of a meaning

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id": "meaning1",
    "label": "Meaning 1",
    "type": "VALUES_MAPPING",
    "mappings": [
       {"from": "value_1", "to": "value_a"},
       {"from": "value_2", "to": "value_b"}
    ],
    "normalizationMode": "NORMALIZED",
    "description": "This is a sample meaning description.",
    "detectable": False 
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the meaning"
    },
    "label": {
      "type": "string",
      "description": "Label of the meaning"
    },
    "type": {
      "type": "string",
      "description": "Type of the meaning. One of `DECLARATIVE`, `VALUES_LIST`, `VALUES_MAPPING`, `PATTERN`"
    },
    "description": {
      "type": "string",
      "description": "Description of the meaning"
    },
    "values": {
      "type": "array",
      "description": "For `VALUES_LIST` meanings, the valid values"
    },
    "mappings": {
      "type": "array",
      "description": "For `VALUES_MAPPING` meanings, the valid mappings"
    },
    "pattern": {
      "type": "array",
      "description": "For `PATTERN` meanings, the pattern"
    },
    "normalizationMode": {
      "type": "string",
      "description": "String normalization mode used to match values. One of `EXACT`, `LOWERCASE`, `NORMALIZED` (remove accents) for types `VALUES_LIST` and `VALUES_MAPPING`. One of `EXACT`, `LOWERCASE` for `PATTERN`"
    },
    "detectable": {
      "type": "boolean",
      "description": "Whether DSS should consider assigning the meaning to columns set to Auto-detect"
    }
  }
}

Update meaning definition
PUT/meanings/{meaningId}

Updates the definition of a Meaning.

🔒 Required privileges : Admin

Example URI

PUT /meanings/dept_code
URI Parameters
HideShow
meaningId
string (required) Example: dept_code

the ID of a meaning

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "id": "meaning1",
    "label": "Meaning 1",
    "type": "VALUES_MAPPING",
    "mappings": [
       {"from": "value_1", "to": "value_a"},
       {"from": "value_2", "to": "value_b"}
    ],
    "normalizationMode": "NORMALIZED",
    "description": "This is a sample meaning description.",
    "detectable": False 
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the meaning"
    },
    "label": {
      "type": "string",
      "description": "Label of the meaning"
    },
    "type": {
      "type": "string",
      "description": "Type of the meaning. One of `DECLARATIVE`, `VALUES_LIST`, `VALUES_MAPPING`, `PATTERN`"
    },
    "description": {
      "type": "string",
      "description": "Description of the meaning"
    },
    "values": {
      "type": "array",
      "description": "For `VALUES_LIST` meanings, the valid values"
    },
    "mappings": {
      "type": "array",
      "description": "For `VALUES_MAPPING` meanings, the valid mappings"
    },
    "pattern": {
      "type": "array",
      "description": "For `PATTERN` meanings, the pattern"
    },
    "normalizationMode": {
      "type": "string",
      "description": "String normalization mode used to match values. One of `EXACT`, `LOWERCASE`, `NORMALIZED` (remove accents) for types `VALUES_LIST` and `VALUES_MAPPING`. One of `EXACT`, `LOWERCASE` for `PATTERN`"
    },
    "detectable": {
      "type": "boolean",
      "description": "Whether DSS should consider assigning the meaning to columns set to Auto-detect"
    }
  }
}
Response  204

Plugins

Plugins

List Installed plugins
GET/plugins/

Lists the plugins installed on the instance (including dev plugins)

🔒 Required privileges : ADMIN

Example URI

GET /plugins/
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "mini-audit",
    "version": "v1.0",
    "isDev": false,
    "meta": {
      "label": "Auditing a dataset",
      "description": "This plugin computes simple metrics on a dataset"
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Plugin

Upload a new plugin
POST/plugins/{pluginId}/upload

Uploads a file as the zip of a plugin and installs it. Fails if the plugin is already installed.

🔒 Required privileges : ADMIN

Example URI

POST /plugins/pluginId/upload
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  204

Update a plugin
POST/plugins/{pluginId}/update

Uploads a file as the zip of a plugin and re-installs it. Fails if the plugin is not already installed.

🔒 Required privileges : ADMIN

Example URI

POST /plugins/pluginId/update
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  204

Plugin contents

For development plugins, it is possible to list, get and set files inside the plugin.

List files in plugin
GET/plugins/{pluginId}/contents/

Lists the contents of a plugin

🔒 Required privileges : ADMIN

Example URI

GET /plugins/pluginId/contents/
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "name": "a.txt",
    "path": "/a.txt",
    "mimeType": "application/text"
  },
  {
    "name": "test",
    "path": "/test",
    "children": [
      {
        "name": "b.txt",
        "path": "/b.txt",
        "mimeType": "application/text"
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Download file from plugin
GET/plugins/{pluginId}/contents/{path}

Downloads the file with the specified relative path in the plugin.

🔒 Required privileges : ADMIN

Example URI

GET /plugins/pluginId/contents/path
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

path
string (required) 

the path to the file from the root of the plugin

Response  200
HideShow
Body
The file's contents, as a stream

Upload file to plugin
POST/plugins/{pluginId}/contents/{path}

Uploads a file to the plugin. The file is sent as the body of the request

🔒 Required privileges : ADMIN

Example URI

POST /plugins/pluginId/contents/path
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

path
string (required) 

the path to the file from the root of the plugin

Response  204

API Services

API Services

List API Services
GET/projects/{projectKey}/apiservices/

Lists the API services of a project.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/projectKey/apiservices/
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "my-service",
    "publicAccess": "true",
    "endpoints": [
      {
        "id": "predict-revenue",
        "type": "STD_PREDICTION"
      },
      {
        "id": "predict-churn",
        "type": "CUSTOM_PREDICTION"
      }
    ]
  }
]

List packages
GET/projects/{projectKey}/apiservices/{serviceId}/packages/

Lists the generated packages of an API service.

🔒 Required privileges : READ_CONF

Example URI

GET /projects/projectKey/apiservices/serviceId/packages/
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

serviceId
string (required) 

the id of a service in this project

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "v1",
    "createdOn": 1445265534000
  },
  {
    "id": "v2",
    "createdOn": 1445878484000
  }
]

Download package archive
GET/projects/{projectKey}/apiservices/{serviceId}/packages/{packageId}/archive

Download a package archive of an API service.

🔒 Required privileges : READ_CONF, READ_DATA

Example URI

GET /projects/projectKey/apiservices/serviceId/packages/packageId/archive
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

serviceId
string (required) 

the id of a service in this project

packageId
string (required) 

the id of a package in this service

Response  200
HideShow
Headers
Content-Type: application/zip
Content-Disposition: attachment; filename={serviceId}_{packageId}.zip

Generate package
POST/projects/{projectKey}/apiservices/{serviceId}/packages/{packageId}

Generate a package of an API service.

🔒 Required privileges : WRITE_CONF

Example URI

POST /projects/projectKey/apiservices/serviceId/packages/packageId
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

serviceId
string (required) 

the id of a service in this project

packageId
string (required) 

the id of the new package

Response  200
HideShow
Headers
Content-Type: text/plain
Body
Created package {packageId}

Delete package
DELETE/projects/{projectKey}/apiservices/{serviceId}/packages/{packageId}

Delete a package of an API service.

🔒 Required privileges : WRITE_CONF

Example URI

DELETE /projects/projectKey/apiservices/serviceId/packages/packageId
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

serviceId
string (required) 

the id of a service in this project

packageId
string (required) 

the id of a package in this service

Response  200
HideShow
Headers
Content-Type: text/plain
Body
Deleted package {packageId}

Bundles, Design-side

Bundles of a project

List exported bundles
GET/projects/{projectKey}/bundles/exported

Retrieves the list of exported bundles for a project

🔒 Required privileges : ADMIN (on project)

Example URI

GET /projects/MYPROJECT/bundles/exported
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "bundles": [
    {
      "bundleId": "v1",
      "contentSummary": {},
      "exportManifest": {}
    }
  ]
}

Get details about a bundle
GET/projects/{projectKey}/bundles/exported/{bundleId}

🔒 Required privileges : ADMIN (on project)

Example URI

GET /projects/MYPROJECT/bundles/exported/v1
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

bundleId
string (required) Example: v1

the id of the bundle

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "bundles": [
    {
      "bundleId": "v1",
      "contentSummary": {},
      "exportManifest": {},
      "changelog": {}
    }
  ]
}

Download a bundle
GET/projects/{projectKey}/bundles/exported/{bundleId}/archive

Downloads a bundle

🔒 Required privileges : ADMIN (on project)

Example URI

GET /projects/MYPROJECT/bundles/exported/v1/archive
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

bundleId
string (required) Example: v1

Identifier of the bundle to activate for this project

Response  200
HideShow
Headers
Content-Type: application/zip

Create a new bundle
PUT/projects/{projectKey}/bundles/exported/

Create a new bundle

🔒 Required privileges : ADMIN (on project)

Example URI

PUT /projects/MYPROJECT/bundles/exported/
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

  • bundleId: v1 (string) - the id of the new bundle
Response  204

Bundles, Automation-side

Bundles of a project

List imported bundles
GET/projects/{projectKey}/bundles

Retrieves the list of imported bundles for a project

🔒 Required privileges : ADMIN (on project)

Example URI

GET /projects/MYPROJECT/bundles
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "bundles": [
    {
      "bundleId": "v1",
      "contentSummary": {},
      "exportManifest": {}
    }
  ]
}

Import bundle from archive file
POST/projects/{projectKey}/bundles/imported/actions/importFromArchive{?archivePath}

Retrieves the list of imported bundles for a project

🔒 Required privileges : ADMIN (on project)

Example URI

POST /projects/MYPROJECT/bundles/imported/actions/importFromArchive?archivePath=/home/data/import/bundle-v1.zip
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

archivePath
string (required) Example: /home/data/import/bundle-v1.zip

the absolute path on the Automation node host, where the bundle resides

Response  204

Activate a bundle
POST/projects/{projectKey}/bundles/imported/{bundleId}/actions/activate

Activates a bundle

🔒 Required privileges : ADMIN (on project)

Example URI

POST /projects/MYPROJECT/bundles/imported/v1/actions/activate
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

bundleId
string (required) Example: v1

Identifier of the bundle to activate for this project

Response  204

New project

Create project from a bundle
POST/projectsFromBundle

Creates a project from a bundle. The bundle Zip content must be sent using multipart, as a “file” part

🔒 Required privileges : ADMIN (global)

Example URI

POST /projectsFromBundle
Response  204

Create project from a bundle
POST/projectsFromBundle/fromArchive{?archivePath}

Creates a project from a bundle. The bundle Zip must already be present as a file on the Automation node host

🔒 Required privileges : ADMIN (global)

Example URI

POST /projectsFromBundle/fromArchive?archivePath=
URI Parameters
HideShow
archivePath
string (required) 

Absolute path to the location of the bundle on the Automation node host

Response  204

SQL queries

SQL queries

Start a query
POST/sql/queries

Start the execution of a query.

This call starts the execution of the query and returns the result’s schema, along with an identifier for the query.

🔒 Required privileges : RUN_CODE

Example URI

POST /sql/queries
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "connection": "Hello, world!",
  "datasetFullName": "Hello, world!",
  "database": "Hello, world!",
  "query": "Hello, world!",
  "preQueries": [
    "Hello, world!"
  ],
  "postQueries": [
    "Hello, world!"
  ],
  "type": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "connection": {
      "type": "string",
      "default": "empty"
    },
    "datasetFullName": {
      "type": "string",
      "default": "empty"
    },
    "database": {
      "type": "string",
      "default": "empty"
    },
    "query": {
      "type": "string"
    },
    "preQueries": {
      "type": "array",
      "default": [
        "empty"
      ],
      "description": "A list of queries to run before the actual query"
    },
    "postQueries": {
      "type": "array",
      "default": [
        "empty"
      ],
      "description": "A list of queries to run after the actual query"
    },
    "type": {
      "type": "string",
      "default": "sql"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "queryId" : "e98f95f2-678b-4277-ac01-c5ff52b8cd9a",
    "hasResults" : true,
    "schema" : [
        {
            "name" : "col_1",
            "type": "string"
        },
        {
            "name" : "col_2",
            "type": "int"
        },
        ...
    ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Stream the data
GET/sql/queries/{queryId}/stream{?format}{?formatParams}

Streams the results of a query.

🔒 Required privileges : RUN_CODE

Example URI

GET /sql/queries/queryId/stream?format=?formatParams=
URI Parameters
HideShow
queryId
string (required) 

Identifier returned by the start-streaming call

format
string (optional) Default: json 
formatParams
object (optional) 

Output format parameters (depends on the format)

Response  200
HideShow

The Content-Type and the content of the request may change according to the requested format.

The default (json) output will produce an array of arrays representing the data:

Body
[
    [ "a", "1"],
    [ "b", "2"],
    ...
]

Verify a query
GET/sql/queries/{queryId}/finish-streaming

Start the execution of a query

🔒 Required privileges : RUN_CODE

Example URI

GET /sql/queries/queryId/finish-streaming
URI Parameters
HideShow
queryId
string (required) 

Identifier returned by the start-streaming call

Response  200
HideShow

Verifies that the query identified by queryId finished successfully on the server side. If not, returns the exception and a 500 status code.

Headers
Content-Type: application/text
Body
exception

Connections

Connections

List connections
GET/admin/connections

List all the connections available on the DSS instance.

This call retrieves a dictionary of Connection objects as defined in GET connection.

🔒 Required privileges : Admin

Example URI

GET /admin/connections
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "my-connection": {
        "name" : "my-connection",
        "type" : "Vertica",
        "allowWrite" : true,
        "allowManagedDatasets" : true,
        "usableBy" : "ALL",
        "allowedGroups" : [],
        "params" : {
            "db" : "dbname",
            "properties" : {},
            "user" : "dbadmin",
            "host" : "127.0.0.1",
            "password" : "thedbpassword"
        },
    }
}

Create connection
POST/admin/connections

Creates a connection on DSS.

The parameters of a connection are specific to each type of connection. It is recommended that you have a look at the parameters of a similar connection to create your own.

🔒 Required privileges : Admin

Example URI

POST /admin/connections
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "new-connection",
  "type": "PostgreSQL",
  "params": {
    "db": "dbname",
    "user": "myuser",
    "host": "127.0.0.1",
    "password": "thedbpassword"
  }
}
Response  200

Connection

🔒 Required privileges : Admin

Get connection
GET/admin/connection/{connectionName}

Gets a connection

WARNING : The returned object may contain other attributes but you should not rely on them since they could be modified or removed in future releases without notice.

Example URI

GET /admin/connection/connectionName
URI Parameters
HideShow
connectionName
string (required) 

the name of a connection in DSS

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "Hello, world!",
  "type": "Hello, world!",
  "allowWrite": true,
  "allowManagedDatasets": true,
  "usableBy": "Hello, world!",
  "allowedGroups": [
    "Hello, world!"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "allowWrite": {
      "type": "boolean"
    },
    "allowManagedDatasets": {
      "type": "boolean",
      "description": "Set to true to allow the connection to provide [Managed datasets](http://doc.dataiku.com/dss/latest/concepts/#managed-and-external-datasets)"
    },
    "usableBy": {
      "type": "string",
      "description": "\"ALL\" or \"ALLOWED\", who may use this connection"
    },
    "allowedGroups": {
      "type": "array",
      "description": "Ignored if usableBy is ALL"
    }
  }
}

Update connection
PUT/admin/connection/{connectionName}

The Connection object given as parameter in of a PUT call MUST have been previously obtained from a GET connection call at the same URL.

**WARNING : ** the type and names attributes may not be modified. The object obtained with the GET method may contain undocumented attributes. You should not modify them as it could create an invalid state and thoses attributes may be removed in future releases without notice.

🔒 Required privileges : Admin

Example URI

PUT /admin/connection/connectionName
URI Parameters
HideShow
connectionName
string (required) 

the name of a connection in DSS

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "type": "MySQL",
  "name": "LocalMySQL",
  "allowWrite": true,
  "allowManagedDatasets": true,
  "usableBy": "ALL",
  "allowedGroups": [],
  "params": {
    "db": "dbname",
    "user": "myuser",
    "host": "127.0.0.1",
    "password": "thedbpassword"
  }
}
Response  204

Delete connection
DELETE/admin/connection/{connectionName}

Removes the connection from DSS.

WARNING : No check is performed to ensure that the connection is not in use for a dataset.

🔒 Required privileges : Admin

Example URI

DELETE /admin/connection/connectionName
URI Parameters
HideShow
connectionName
string (required) 

the name of a connection in DSS

Response  204

Security

Users

List users
GET/admin/users/{?connected}

Retrieves the list of DSS users as a list of User objects as defined in GET user.

**WARNING : ** the connected status of the users is detected using WebSockets. If the WebSockets are disabled (for example if your firewall blocks them), some or all of the connected users may not be listed as connected.

🔒 Required privileges : Global admin

Example URI

GET /admin/users/?connected=
URI Parameters
HideShow
connected
boolean (optional) Default: false 
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "login": "Hello, world!",
    "sourceType": "Hello, world!",
    "displayName": "Hello, world!",
    "groups": [
      "Hello, world!"
    ],
    "codeAllowed": "Hello, world!"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create user
POST/admin/users

Adds a user account on DSS.

Example URI

POST /admin/users
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "login": "newlogin",
  "displayName": "The new user",
  "groups": [
    "data_scientists"
  ],
  "password": "unencrypted password"
}
Response  200

User

Get user
GET/admin/users/{login}

Retrieves a User object describing a DSS user

WARNING : The returned object may contain other attributes but you should not rely on them since they could be modified or removed in future releases without notice.

🔒 Required privileges : Admin

Example URI

GET /admin/users/login
URI Parameters
HideShow
login
string (required) 

the login of a DSS user

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "login": "Hello, world!",
  "sourceType": "Hello, world!",
  "displayName": "Hello, world!",
  "groups": [
    "Hello, world!"
  ],
  "codeAllowed": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "login": {
      "type": "string"
    },
    "sourceType": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    },
    "groups": {
      "type": "array"
    },
    "codeAllowed": {
      "type": "string",
      "description": "True if the user is allowed to write native code"
    }
  }
}

Update user
PUT/admin/users/{login}

The User object given as body of the PUT call MUST have been previously obtained from a GET user call at the same URL.

The object obtained with the GET method may contain undocumented attributes. You should not modify them as it could create an invalid state and thoses attributes may be removed in future releases without notice.

🔒 Required privileges : Admin

Example URI

PUT /admin/users/login
URI Parameters
HideShow
login
string (required) 

the login of a DSS user

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "login": "mattsco",
  "displayName": "Matthieu Modified",
  "groups": [
    "administrators",
    "data_scientists"
  ],
  "codeAllowed": true
}
Response  204

Delete user
DELETE/admin/users/{login}

Deletes a DSS user

🔒 Required privileges : Admin

Example URI

DELETE /admin/users/login
URI Parameters
HideShow
login
string (required) 

the login of a DSS user

Response  204

Groups

List groups
GET/admin/groups

Retrieves the list of DSS groups as a list of Group objects as defined in GET group.

🔒 Required privileges : Admin

Example URI

GET /admin/groups
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "name": "administrators",
    "description": "DSS administrators",
    "admin": true,
    "sourceType": "LOCAL"
  }
]

Create group
POST/admin/groups

Add a user group to DSS

🔒 Required privileges : Admin

Example URI

POST /admin/groups
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "New Group for business",
  "admin": false,
  "description": "This group is for business users"
}
Response  200

Group

Get group
GET/admin/groups/{groupname}

Retrieves a Group object describing a DSS user group, used for access control on connections and projects.

WARNING : The returned object may contain other attributes but you should not rely on them since they could be modified or removed in future releases without notice.

🔒 Required privileges : Admin

Example URI

GET /admin/groups/groupname
URI Parameters
HideShow
groupname
string (required) 

the name of a DSS group

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "Hello, world!",
  "description": "Hello, world!",
  "admin": true,
  "sourceType": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "admin": {
      "type": "boolean",
      "description": "Whether this group gives administrative rights on DSS"
    },
    "sourceType": {
      "type": "string"
    }
  }
}

Update group
PUT/admin/groups/{groupname}

The Group object given as parameter in of a PUT call MUST have been previously obtained from a GET group call at the same URL.

The object with the GET method may contain undocumented attributes. You should not modify them as it could create an invalid state and thoses attributes may be removed in future releases without notice.

🔒 Required privileges : Admin

Example URI

PUT /admin/groups/groupname
URI Parameters
HideShow
groupname
string (required) 

the name of a DSS group

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "ANALYSTS",
  "admin": false,
  "description": "This group is suited for business analysts"
}
Response  204

Delete group
DELETE/admin/groups/{groupname}

Deletes a DSS users group

🔒 Required privileges : Admin

Example URI

DELETE /admin/groups/groupname
URI Parameters
HideShow
groupname
string (required) 

the name of a DSS group

Response  204

DSS administration

Global settings

Get general settings
GET/admin/general-settings

This calls retrieves the object representing DSS settings.

🔒 Required privileges : Admin

Example URI

GET /admin/general-settings
Response  200
HideShow
Headers
Content-Type: application/json
DSS-API-Version: Version of the API server handling the request
DSS-Version: Version of the DSS backend answering the request
Body
{
    "ldapSettings" : { ... },
    "hiveSettings" : { ... },
    ...
}

Save general settings
PUT/admin/general-settings

This calls saves the DSS settings. You must only PUT an object that you acquired previously via the corresponding GET call

🔒 Required privileges : Admin

Example URI

PUT /admin/general-settings
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "ldapSettings" : { ... },
    "hiveSettings" : { ... },
    ...
}
Response  204

Platform logs

List logs
GET/admin/logs

DSS uses a number of log files, for example for the web server, the notebooks or the core backend plateform.

This call list all the available logs but NOT the logs generated during the jobs execution.

For these, see the Jobs section.

🔒 Required privileges : Admin

Example URI

GET /admin/logs
Response  200
HideShow
Headers
Content-Type: application/json
DSS-API-Version: Version of the API server handling the request
DSS-Version: Version of the DSS backend answering the request
Body
{
    "logs" : [
        {
           "name" : "access.log",
           "totalSize" : 571166942,
           "lastModified" : 1435840900000
        },
        ...
    ]
}

Log

Get log content
GET/admin/logs/{name}

Retrieves the log file with the specified name.

🔒 Required privileges : Admin

Example URI

GET /admin/logs/name
URI Parameters
HideShow
name
string (required) 

the name of a log file

Response  200
HideShow
Headers
Content-Type: text/plain
DSS-API-Version: Version of the API server handling the request
DSS-Version: Version of the DSS backend answering the request

Global variables

List variables
GET/admin/variables

Retrieves the DSS instance global variable as a dictionary.

🔒 Required privileges : Admin

Example URI

GET /admin/variables
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "variable_1": "value",
    ...
}

Save variables
PUT/admin/variables

Save the global variables for the DSS instance.

WARNING : this will overwrite all previous variables, so to update or add only some variables, you should first list the current variables with a GET call.

🔒 Required privileges : Admin

Example URI

PUT /admin/variables
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "variable_1": "value",
    ...
}
Response  204

Internal Metrics

Internal Metrics

List internal metrics
GET/internal-metrics{?name}{?type}

Retrieves the DSS instance internal metrics as a dictionary.

🔒 Required privileges : Admin

Example URI

GET /internal-metrics?name=my.metric.name?type=gauges
URI Parameters
HideShow
name
string (optional) Example: my.metric.name

name of the metric

type
string (optional) Example: gauges

type of the metric. Can be gauges, counters, histograms, meters, timers

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "counters": {
        "metric.dotted.name": {
            "variable_1": value,
            ...
        }
    },
    "gauges": {
        ...
    },
    "histograms": {
        ...
    },
    "meters": {
        ...
    },
    "timers": {
        ...
    },
    "version": "3.0.0"
}

Generated by aglio on 07 Jul 2017