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/

curl --user <USER_API_KEY>: -H "Content-Type: application/json" -X GET http://mymachine:port/public/api/projects/

Other notes

Many API calls may return 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

Project Folders

Root Project Folder

Get root project folder
GET/project-folders/

Get the definition of the root project folder. Only the items on which the API key has the READ privilege for project folders (children) and READ_CONF for projects privilege will be listed.

Example URI

GET /project-folders/
Response  200
HideShow

Definition of the root project folder

Headers
Content-Type: application/json
Body
{
  "id": "Hello, world!",
  "name": "Hello, world!",
  "parentId": "Hello, world!",
  "childrenIds": [
    "Hello, world!"
  ],
  "projectKeys": [
    "Hello, world!"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the project folder"
    },
    "name": {
      "type": "string",
      "description": "name of the project folder (or null if root project folder)"
    },
    "parentId": {
      "type": "string",
      "description": "the ID of the parent project folder (or null if root project folder)"
    },
    "childrenIds": {
      "type": "array",
      "description": "the list of the ID of this project folder's children"
    },
    "projectKeys": {
      "type": "array",
      "description": "the list of the project keys inside this project folder"
    }
  }
}

Project Folder

Get a project folder
GET/project-folders/{folderId}

Get the definition of a project folder. Only the items on which the API key has the READ privilege for project folders (children) and READ_CONF for projects privilege will be listed.


πŸ”’ Required privileges : READ on this project folder

Example URI

GET /project-folders/KdLmPU6
URI Parameters
HideShow
folderId
string (required) Example: KdLmPU6

the ID of a project folder

The folderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

Response  200
HideShow

Definition of the project folder

Headers
Content-Type: application/json
Body
{
  "id": "Hello, world!",
  "name": "Hello, world!",
  "parentId": "Hello, world!",
  "childrenIds": [
    "Hello, world!"
  ],
  "projectKeys": [
    "Hello, world!"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the project folder"
    },
    "name": {
      "type": "string",
      "description": "name of the project folder (or null if root project folder)"
    },
    "parentId": {
      "type": "string",
      "description": "the ID of the parent project folder (or null if root project folder)"
    },
    "childrenIds": {
      "type": "array",
      "description": "the list of the ID of this project folder's children"
    },
    "projectKeys": {
      "type": "array",
      "description": "the list of the project keys inside this project folder"
    }
  }
}

Get project folder settings
GET/project-folders/{folderId}/settings

Get the settings of a project folder


πŸ”’ Required privileges : ADMIN on this project folder

Example URI

GET /project-folders/KdLmPU6/settings
URI Parameters
HideShow
folderId
string (required) Example: KdLmPU6

the ID of a project folder

The folderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

Response  200
HideShow

Settings of the project folder

Headers
Content-Type: application/json
Body
{
  "name": "my folder",
  "owner": "admin",
  "permissions": [
    {
      "group": "data_scientists",
      "read": true,
      "writeContents": true,
      "admin": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the project folder"
    },
    "owner": {
      "type": "string",
      "description": "login of the owner of the project folder"
    },
    "permissions": {
      "type": "array",
      "description": "the list of the permissions of the project folder"
    }
  }
}

Update project folder settings
PUT/project-folders/{folderId}/settings

Update the settings of a project folder


πŸ”’ Required privileges : ADMIN on this project folder

Example URI

PUT /project-folders/KdLmPU6/settings
URI Parameters
HideShow
folderId
string (required) Example: KdLmPU6

the ID of a project folder

The folderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "my folder modified",
  "owner": "admin",
  "permissions": [
    {
      "group": "data_scientists",
      "read": true,
      "writeContents": true,
      "admin": true
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the project folder"
    },
    "owner": {
      "type": "string",
      "description": "login of the owner of the project folder"
    },
    "permissions": {
      "type": "array",
      "description": "the list of the permissions of the project folder"
    }
  }
}
Response  204

Move a project folder
POST/project-folders/{folderId}/move{?destination}

Move a project folder into another project folder (change its parent) along with its content. You cannot move a project folder into one of its sub-folder.


πŸ”’ Required privileges : ADMIN on this project folder, WRITE_CONTENTS on the destination project folder

Example URI

POST /project-folders/KdLmPU6/move?destination=dgKywsx
URI Parameters
HideShow
folderId
string (required) Example: KdLmPU6

the ID of a project folder to move

The folderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

destination
string (required) Example: dgKywsx

the ID of the destination project folder

The destination (project folder ID) can be found from the get project folder API call or in the URL when accessing DSS GUI.

Response  204

Delete project
DELETE/project-folders/{folderId}

Permanently deletes a project folder. It must be empty: no sub-folders and no projects inside


πŸ”’ Required privileges : ADMIN (on this project folder)

Example URI

DELETE /project-folders/KdLmPU6
URI Parameters
HideShow
folderId
string (required) Example: KdLmPU6

the key of the project folder to delete

The folderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

Response  204

Create a sub-project folder
POST/project-folders/{folderId}/children{?name}

Create a sub-project folder within the current project folder.


πŸ”’ Required privileges : WRITE_CONTENTS on the current project folder

Example URI

POST /project-folders/KdLmPU6/children?name=my_sub_folder
URI Parameters
HideShow
folderId
string (required) Example: KdLmPU6

the ID of a project folder to move

The folderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

name
string (required) Example: my_sub_folder

the name of the new project folder

Response  200
HideShow

Definition of the newly created project folder

Headers
Content-Type: application/json
Body
{
  "id": "Hello, world!",
  "name": "Hello, world!",
  "parentId": "Hello, world!",
  "childrenIds": [
    "Hello, world!"
  ],
  "projectKeys": [
    "Hello, world!"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the project folder"
    },
    "name": {
      "type": "string",
      "description": "name of the project folder (or null if root project folder)"
    },
    "parentId": {
      "type": "string",
      "description": "the ID of the parent project folder (or null if root project folder)"
    },
    "childrenIds": {
      "type": "array",
      "description": "the list of the ID of this project folder's children"
    },
    "projectKeys": {
      "type": "array",
      "description": "the list of the project keys inside this project folder"
    }
  }
}

Move a project
POST/project-folders/{folderId}/projects/{projectKey}/move{?destination}

Move a project within the current project folder to another project folder


πŸ”’ Required privileges : WRITE_CONTENTS on the destination project folder, Admin of project

Example URI

POST /project-folders/KdLmPU6/projects/MYPROJECT/move?destination=dgKywsx
URI Parameters
HideShow
folderId
string (required) Example: KdLmPU6

the ID of a project folder where is the project is

The folderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

projectKey
string (required) Example: MYPROJECT

the ID of the project to move

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

destination
string (required) Example: dgKywsx

the ID of the destination project folder

The destination (project folder ID) can be found from the get project folder API call or in the URL when accessing DSS GUI.

Response  204

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{?projectFolderId}

Creates a new project


πŸ”’ Required privileges : Admin for project creation, WRITE_CONTENTS on the project folder

Example URI

POST /projects?projectFolderId=KdLmPU6
URI Parameters
HideShow
projectFolderId
string (optional) Example: KdLmPU6

the ID of the project folder in which the new project will be created (if not provided, will defaults to root project folder)

The projectFolderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

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 : READ_CONF (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}{?dropData}

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


πŸ”’ Required privileges : ADMIN (on this project)

Example URI

DELETE /projects/MYPROJECT?dropData=
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.

dropData
boolean (optional) Default: false 

Drop the data from any managed datasets

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 

Export uploaded datasets data

exportManaged
boolean (optional) Default: true 

Export managed Filesystem datasets data

exportAnalysisModels
boolean (optional) Default: true 

Export trained models that are in analyses (not deployed in the flow).

exportSavedModels
boolean (optional) Default: true 

Export saved models (deployed in the flow).

Response  200
HideShow
Headers
Content-Type: application/zip

Duplicate project
POST/projects/{projectKey}/duplicate

Duplicate a project.

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


πŸ”’ Required privileges : ADMIN (on this project)

Example URI

POST /projects/MYPROJECT/duplicate
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
{
    "targetProjectKey": "COPYOFMYPROJECT",
    "targetProjectName": "Copy+of+my+project"
    "targetProjectFolderId": "KdLmPU6" /* ID of a project folder. If null, will defaults to root project folder */
    "duplicationMode": "MINIMAL" /* MINIMAL, SHARING, FULL, NONE */
    "exportAnalysisModels": true
    "exportSavedModels": true
    "exportGitRepository": true
    "exportInsightsData": true
    "exportUploads": true
    "exportAllInputDatasets": true
    "exportAllInputManagedFolders": true
    "exportAllDatasets": false
    "exportManagedFolders": false
    "shareAllInputDatasets": false
    "remapping":{
        "connections":[
            {
                "source":"filesystem_source"
                "target":"filesystem_target"
            }
        ]
        "codeEnvs":[
            {
                "source":"codenv_source"
                "target":"codenv_target"
            }
        ]
    },
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "projectKey": "MYPROJECT"
    "targetProjectKey": "COPYOFMYPROJECT"
    "targetProjectFolderId": "KdLmPU6"
}

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

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

Retrieves project-level tags for this project.


πŸ”’ Required privileges : READ_CONF (on project)

Example URI

GET /projects/MYPROJECT/tags
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
{
  "tags": {
    "origin:sql_import": {
      "color": "#ee874a"
    },
    "creator:admin": {
      "color": "#28aadd"
    },
    "pg": {
      "color": "#a088bd"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tags": {
      "type": "object",
      "properties": {},
      "description": "Dictionary of tags for this project."
    }
  }
}

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

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


πŸ”’ Required privileges : WRITE_CONF (on project)

Example URI

PUT /projects/MYPROJECT/tags
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
{
  "tags": {
    "origin:sql_import": {
      "color": "#ee874a"
    },
    "creator:admin": {
      "color": "#28aadd"
    },
    "pg": {
      "color": "#a088bd"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tags": {
      "type": "object",
      "properties": {},
      "description": "Dictionary of tags for this project."
    }
  }
}
Response  204

Workspaces

Workspaces

List workspaces
GET/workspaces

Lists the workspaces. Only the workspaces on which the API key has the READ privilege will be listed.

Example URI

GET /workspaces
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "workspaceKey": "Hello, world!",
    "displayName": "Hello, world!",
    "color": "Hello, world!",
    "description": "Hello, world!",
    "permissions": [
      {
        "user": "Hello, world!",
        "group": "Hello, world!",
        "admin": true,
        "write": true,
        "read": true
      }
    ],
    "currentUserPermissions": {
      "user": "Hello, world!",
      "group": "Hello, world!",
      "admin": true,
      "write": true,
      "read": true
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create workspace
POST/workspaces

Creates a new workspace


πŸ”’ Required privileges : mayCreateWorkspaces (global permission)

Example URI

POST /workspaces
Request
HideShow

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

Headers
Content-Type: application/json
Body
{
  "workspaceKey": "The workspace key of the new workspace",
  "displayName": "Name of the workspace",
  "color": "#996633",
  "description": "Description of the workspace"
}
Response  200
HideShow
Body
{
  "msg": "Created workspace The workspace key of the new workspace"
}

Workspace

Get workspace settings
GET/workspaces/{workspaceKey}

Retrieves settings about this workspace.


πŸ”’ Required privileges : READ, also known as β€œMember” (on workspace). However, if the user is not ADMIN, the permissions array will not be defined.

Example URI

GET /workspaces/MY_WORKSPACE
URI Parameters
HideShow
workspaceKey
string (required) Example: MY_WORKSPACE

the key of a workspace

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

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

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "workspaceKey": "Hello, world!",
  "displayName": "Hello, world!",
  "color": "Hello, world!",
  "description": "Hello, world!",
  "permissions": [
    {
      "user": "Hello, world!",
      "group": "Hello, world!",
      "admin": true,
      "write": true,
      "read": true
    }
  ],
  "currentUserPermissions": {
    "user": "Hello, world!",
    "group": "Hello, world!",
    "admin": true,
    "write": true,
    "read": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "workspaceKey": {
      "type": "string",
      "description": "The key of the workspace"
    },
    "displayName": {
      "type": "string",
      "description": "The name of the workspace, as displayed in the User Interface"
    },
    "color": {
      "type": "string",
      "description": "The background color of the workspace (using #xxxxxx syntax)"
    },
    "description": {
      "type": "string",
      "description": "The description of the workspace"
    },
    "permissions": {
      "type": "array",
      "description": "Permissions controlling who is a member, contributor or admin of the workspace"
    },
    "currentUserPermissions": {
      "type": "object",
      "properties": {
        "user": {
          "type": "string",
          "description": "Name of the user this permission applies to. Missing if the permission applies to a group"
        },
        "group": {
          "type": "string",
          "description": "Name of the group this permission applies to. Missing if the permission applies to a user"
        },
        "admin": {
          "type": "boolean",
          "description": "true if the permission grants administrator access"
        },
        "write": {
          "type": "boolean",
          "description": "true if the permission grants contributor access"
        },
        "read": {
          "type": "boolean",
          "description": "true if the permission grants member access"
        }
      },
      "description": "Permissions of the current user (read-only)"
    }
  }
}

Update workspace settings
PUT/workspaces/{workspaceKey}

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


πŸ”’ Required privileges : ADMIN (on workspace)

Example URI

PUT /workspaces/MY_WORKSPACE
URI Parameters
HideShow
workspaceKey
string (required) Example: MY_WORKSPACE

the key of a workspace

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

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

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "workspaceKey" : "MY_WORKSPACE"
    "displayName": "My workspace",
    "color": "#ff99ff",
    "description": "Updated description",
    "permissions": [
        {
            "user": "jdoe",
            "admin": true,
            "write": true,
            "read": true
        },
        {
            "group": "marketing",
            "admin": false,
            "write": true,
            "read": true
        },
        {
            "group": "readers",
            "admin": false,
            "write": false,
            "read": true
        }
    ]
}
Response  200

Delete workspace
DELETE/workspaces/{workspaceKey}

Permanently deletes a workspace


πŸ”’ Required privileges : ADMIN (on this workspace)

Example URI

DELETE /workspaces/MY_WORKSPACE
URI Parameters
HideShow
workspaceKey
string (required) Example: MY_WORKSPACE

the key of the workspace to delete

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

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

Response  200

Workspace objects

Get workspace objects
GET/workspaces/{workspaceKey}/objects

List the objects in this workspace.


πŸ”’ Required privileges : READ, also known as β€œMember” (on workspace)

Example URI

GET /workspaces/MY_WORKSPACE/objects
URI Parameters
HideShow
workspaceKey
string (required) Example: MY_WORKSPACE

the key of a workspace

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

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

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

Add workspace object
POST/workspaces/{workspaceKey}/objects

Add a DSS object, an application or an HTML link to a workspace


πŸ”’ Required privileges : WRITE, also known as β€œContributor” (on workspace) and mayShareToWorkspaces (global permission) and mayShareToWorkspaces (on the project hosting the DSS object to add)

Example URI

POST /workspaces/MY_WORKSPACE/objects
URI Parameters
HideShow
workspaceKey
string (required) Example: MY_WORKSPACE

the key of a workspace

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

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

Request
HideShow

Add a DSS object to a workspace

Headers
Content-Type: application/json
Body
{
  "reference": {
    "projectKey": "MYPROJECT",
    "type": "DATASET",
    "id": "marketing_data"
  }
}
Request
HideShow

Add an HTML link to a workspace

Headers
Content-Type: application/json
Body
{
  "htmlLink": {
    "name": "Documentation",
    "url": "https://docs.dataiku.com",
    "description": "Official documentation for latest release of Dataiku"
  }
}
Request
HideShow

Add a DSS application to a workspace

Headers
Content-Type: application/json
Body
{
  "appId": "MARKETING_APP"
}

Remove workspace object
DELETE/workspaces/{workspaceKey}/objects/{workspaceObjectId}

Remove an object from a workspace


πŸ”’ Required privileges : WRITE, also known as β€œContributor” (on workspace)

Example URI

DELETE /workspaces/MY_WORKSPACE/objects/abcd1234
URI Parameters
HideShow
workspaceKey
string (required) Example: MY_WORKSPACE

the key of a workspace

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

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

workspaceObjectId
string (required) Example: abcd1234

the id of the object in the workspace

The workspaceObjectId can be found with the list workspace objects API call.

Response  200

Data Collections

Data Collections

List Data Collections
GET/data-collections/

Lists the Data Collections on which the user has READ privilege.

Example URI

GET /data-collections/
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "displayName": "My first Data Collection",
    "color": "#FF0000",
    "description": "Description of the data collection",
    "tags": [
      "some",
      "tags"
    ],
    "id": "OjVsTQ3O",
    "itemCount": 12,
    "lastModifiedOn": 1680307200000
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "displayName": {
        "type": "string",
        "description": "Name of the data collection"
      },
      "color": {
        "type": "string",
        "description": "Color of the data collection (using #RRGGBB syntax)"
      },
      "description": {
        "type": "string",
        "description": "The description of the data collection (markdown)"
      },
      "tags": {
        "type": "array",
        "description": "List of tags of the data collection"
      },
      "id": {
        "type": "string",
        "description": "Id of the data collection"
      },
      "itemCount": {
        "type": "number",
        "description": "Number of objects in the data collection"
      },
      "lastModifiedOn": {
        "type": "number",
        "description": "Timestamp of the last data-collection modification"
      }
    },
    "required": [
      "displayName",
      "color",
      "description",
      "tags",
      "id",
      "itemCount",
      "lastModifiedOn"
    ]
  }
}

Create Data Collection
POST/data-collections/

Creates a new Data Collection

Note The user creating the Data Collection will be added as an administrator.


πŸ”’ Required privileges : mayCreateDataCollections (global permission)

Example URI

POST /data-collections/
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "OjVsTQ3O",
  "displayName": "My first Data Collection",
  "color": "#FF0000",
  "description": "Description of the data collection",
  "tags": [
    "some",
    "tags"
  ],
  "permissions": [
    {
      "user": "user_login",
      "admin": true,
      "write": true,
      "read": true
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the Data Collection (a random id is generated if not provided)"
    },
    "displayName": {
      "type": "string",
      "description": "Name of the data collection"
    },
    "color": {
      "type": "string",
      "description": "Color of the data collection (using #RRGGBB syntax)"
    },
    "description": {
      "type": "string",
      "description": "The description of the data collection (markdown)"
    },
    "tags": {
      "type": "array",
      "description": "List of tags of the data collection"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "admin": {
            "type": "boolean",
            "description": "true if the permission grants administrator access"
          },
          "write": {
            "type": "boolean",
            "description": "true if the permission grants contributor access"
          },
          "read": {
            "type": "boolean",
            "description": "true if the permission grants member access"
          }
        },
        "oneOf": [
          {
            "properties": {
              "user": {
                "type": "string",
                "description": "Name of the user this permission applies to."
              }
            },
            "required": [
              "user"
            ]
          },
          {
            "properties": {
              "group": {
                "type": "string",
                "description": "Name of the group this permission applies to."
              }
            },
            "required": [
              "group"
            ]
          }
        ]
      },
      "description": "List of permissions of the data collection (READER, CONTRIBUTOR or ADMIN)"
    }
  },
  "required": [
    "displayName"
  ],
  "additionalProperties": false
}
Response  201
HideShow

The response contains the id of the created collection

Body
{
    "msg": "Created Data Collection OjVsTQ3O"
    "id": "OjVsTQ3O"
}

Data Collection

Get Data Collection settings
GET/data-collections/{dataCollectionId}

Retrieves the settings of this Data Collection.


πŸ”’ Required privileges : READ, also known as β€œReader” (on this Data Collection). However, if the user is not ADMIN, the permissions array will not be defined.

Example URI

GET /data-collections/OjVsTQ3O
URI Parameters
HideShow
dataCollectionId
string (required) Example: OjVsTQ3O

the id of a Data Collection (in the [A-Za-z0-9]{8} format)

The Data Collection id can be found with the list Data Collections API call or in the URL when accessing DSS GUI.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "OjVsTQ3O",
  "displayName": "My first Data Collection",
  "color": "#FF0000",
  "description": "Description of the data collection",
  "tags": [
    "some",
    "tags"
  ],
  "permissions": [
    {
      "user": "user_login",
      "admin": true,
      "write": true,
      "read": true
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Id of the Data Collection"
    },
    "displayName": {
      "type": "string",
      "description": "Name of the data collection"
    },
    "color": {
      "type": "string",
      "description": "Color of the data collection (using #RRGGBB syntax)"
    },
    "description": {
      "type": "string",
      "description": "The description of the data collection (markdown)"
    },
    "tags": {
      "type": "array",
      "description": "List of tags of the data collection"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "admin": {
            "type": "boolean",
            "description": "true if the permission grants administrator access"
          },
          "write": {
            "type": "boolean",
            "description": "true if the permission grants contributor access"
          },
          "read": {
            "type": "boolean",
            "description": "true if the permission grants member access"
          }
        },
        "oneOf": [
          {
            "properties": {
              "user": {
                "type": "string",
                "description": "Name of the user this permission applies to."
              }
            },
            "required": [
              "user"
            ]
          },
          {
            "properties": {
              "group": {
                "type": "string",
                "description": "Name of the group this permission applies to."
              }
            },
            "required": [
              "group"
            ]
          }
        ]
      },
      "description": "List of permissions of the data collection (READER, CONTRIBUTOR or ADMIN)"
    }
  },
  "required": [
    "displayName",
    "color",
    "description",
    "tags"
  ]
}

Update Data Collection settings
PUT/data-collections/{dataCollectionId}

Updates the settings of this Data Collection. You should only set a settings object that has been obtained through the corresponding GET call.


πŸ”’ Required privileges : ADMIN (on this Data Collection)

Example URI

PUT /data-collections/OjVsTQ3O
URI Parameters
HideShow
dataCollectionId
string (required) Example: OjVsTQ3O

the id of a Data Collection (in the [A-Za-z0-9]{8} format)

The Data Collection id can be found with the list Data Collections API call or in the URL when accessing DSS GUI.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "displayName": "My first Data Collection",
  "color": "#FF0000",
  "description": "Description of the data collection",
  "tags": [
    "some",
    "tags"
  ],
  "permissions": [
    {
      "user": "user_login",
      "admin": true,
      "write": true,
      "read": true
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "displayName": {
      "type": "string",
      "description": "Name of the data collection"
    },
    "color": {
      "type": "string",
      "description": "Color of the data collection (using #RRGGBB syntax)"
    },
    "description": {
      "type": "string",
      "description": "The description of the data collection (markdown)"
    },
    "tags": {
      "type": "array",
      "description": "List of tags of the data collection"
    },
    "permissions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "admin": {
            "type": "boolean",
            "description": "true if the permission grants administrator access"
          },
          "write": {
            "type": "boolean",
            "description": "true if the permission grants contributor access"
          },
          "read": {
            "type": "boolean",
            "description": "true if the permission grants member access"
          }
        },
        "oneOf": [
          {
            "properties": {
              "user": {
                "type": "string",
                "description": "Name of the user this permission applies to."
              }
            },
            "required": [
              "user"
            ]
          },
          {
            "properties": {
              "group": {
                "type": "string",
                "description": "Name of the group this permission applies to."
              }
            },
            "required": [
              "group"
            ]
          }
        ]
      },
      "description": "List of permissions of the data collection (READER, CONTRIBUTOR or ADMIN)"
    }
  },
  "required": [
    "displayName",
    "color",
    "description",
    "tags"
  ],
  "additionalProperties": false
}
Response  200

Delete Data Collection
DELETE/data-collections/{dataCollectionId}

Permanently deletes a Data Collection


πŸ”’ Required privileges : ADMIN (on this Data Collection)

Example URI

DELETE /data-collections/OjVsTQ3O
URI Parameters
HideShow
dataCollectionId
string (required) Example: OjVsTQ3O

the id of a Data Collection (in the [A-Za-z0-9]{8} format)

The Data Collection id can be found with the list Data Collections API call or in the URL when accessing DSS GUI.

Response  200

Data collections objects

Get Data Collection objects
GET/data-collections/{dataCollectionId}/objects

List the objects in this Data Collection.


πŸ”’ Required privileges : READ, also known as β€œReader” (on this Data Collection)

Example URI

GET /data-collections/OjVsTQ3O/objects
URI Parameters
HideShow
dataCollectionId
string (required) Example: OjVsTQ3O

the id of a Data Collection (in the [A-Za-z0-9]{8} format)

The Data Collection id can be found with the list Data Collections API call or in the URL when accessing DSS GUI.

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "type": "DATASET",
    "projectKey": "PROJECT_KEY",
    "id": "dataset_name"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "description": "The type of this object (\"DATASET\" here)"
      },
      "projectKey": {
        "type": "string",
        "description": "The key of the project of this dataset"
      },
      "id": {
        "type": "string",
        "description": "The id of this dataset"
      }
    },
    "required": [
      "type",
      "projectKey",
      "id"
    ]
  }
}

Add Data Collection object
POST/data-collections/{dataCollectionId}/objects

Add an object to a Data Collection


πŸ”’ Required privileges : WRITE, also known as β€œContributor” (on this Data Collection) and mayPublishToDataCollections (global group permission) and publishToDataCollections (on the project hosting the DSS object to add if relevant)

Example URI

POST /data-collections/OjVsTQ3O/objects
URI Parameters
HideShow
dataCollectionId
string (required) Example: OjVsTQ3O

the id of a Data Collection (in the [A-Za-z0-9]{8} format)

The Data Collection id can be found with the list Data Collections API call or in the URL when accessing DSS GUI.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "type": "DATASET",
  "projectKey": "PROJECT_KEY",
  "id": "dataset_name"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "The type of this object (\"DATASET\" here)"
    },
    "projectKey": {
      "type": "string",
      "description": "The key of the project of this dataset"
    },
    "id": {
      "type": "string",
      "description": "The id of this dataset"
    }
  },
  "required": [
    "type",
    "projectKey",
    "id"
  ],
  "additionalProperties": false
}
Response  200

Remove dataset from Data Collection
DELETE/data-collections/{dataCollectionId}/objects/dataset/{projectKey}/{datasetName}

Remove a dataset from a Data Collection


πŸ”’ Required privileges : WRITE, also known as β€œContributor” (on this Data Collection)

Example URI

DELETE /data-collections/OjVsTQ3O/objects/dataset/PROJECT_KEY/DATASET1
URI Parameters
HideShow
dataCollectionId
string (required) Example: OjVsTQ3O

the id of a Data Collection (in the [A-Za-z0-9]{8} format)

The Data Collection id can be found with the list Data Collections API call or in the URL when accessing DSS GUI.

projectKey
string (required) Example: PROJECT_KEY

the key of the project containing the dataset to remove

The projectKey can be found with the list Data Collections objects API call.

datasetName
string (required) Example: DATASET1

the name of the dataset to remove

The dataset name can be found with the list Data Collections objects API call.

Response  200

Flow

Generate flow documentation from default template

Generate flow documentation from default template
POST/projects/{projectKey}/flow/documentation/generate

Start the flow documentation generation using the default template. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated flow documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/flow/documentation/generate
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "exportId": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Generate flow documentation from a custom template

Generate flow documentation from a custom template
POST/projects/{projectKey}/flow/documentation/generate-with-template

Start the flow documentation generation using an attached template file to upload. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated flow documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/flow/documentation/generate-with-template
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

Request
HideShow
Headers
Content-Type: multipart
Body
Multipart file: the template docx file
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "exportId": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Generate flow documentation from a template file in a managed folder

Generate flow documentation from a template file in a managed folder
POST/projects/{projectKey}/flow/documentation/generate-with-template-in-folder{?folderId}{?path}

Start the flow documentation generation using a template file in a managed folder. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated flow documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/flow/documentation/generate-with-template-in-folder?folderId=?path=
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

folderId
string (required) 

the id of the managed folder

path
string (required) 

the path to the file from the root of the folder

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "exportId": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Download flow documentation

Download flow documentation
GET/projects/{projectKey}/flow/documentation/generated/{exportId}

Download the flow documentation. The documentation exportId is obtained through a GET task call on the jobId returned when generating the flow documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/flow/documentation/generated/exportId
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

exportId
string (required) 

the id of the generated flow documentation

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

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

Create managed dataset
POST/projects/{projectKey}/datasets/managed

Creates a new managed dataset (i.e. a dataset whose format/storage details are handled by DSS, you only need to select the name, the connection, and optionally some options).

Valid format option ids include:

  • CSV_EXCEL_GZIP

  • CSV_UNIX_GZIP

  • CSV_ESCAPING_NOGZIP_FORHIVE

  • PARQUET_HIVE

  • ORC


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "name": "name_of_the_new_dataset",
    "creationSettings": {
        "connectionId" : "connection_where_to_store"
    }
}

Or

{
    "name": "name_of_the_new_dataset",
    "creationSettings": {
        "connectionId" : "connection_where_to_store",
        "specificSettings": {
            "formatOptionId": "A format option"
        }
    }
}
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 information

Get full info
GET/projects/{projectKey}/datasets/{datasetName}/info

Retrieves all the information about this dataset.


πŸ”’ Required privileges : READ_DATA on Dataset

Example URI

GET /projects/MYPROJECT/datasets/mydataset/info
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
Return a complex object containing all the information about this dataset, such as its type,
parameters, last buid information, schema, etc.

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"
        }
      }
    ]
  }
}

Import tables

List schemas
GET/projects/{projectKey}/datasets/tables-import/actions/list-schemas{?connectionName}

List schemas in a SQL connection


πŸ”’ Required privileges : WRITE_CONF

Example URI

GET /projects/MYPROJECT/datasets/tables-import/actions/list-schemas?connectionName=
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

connectionName
string (required) 

Name of the SQL connection in which to list schemas. Use @virtual(hive-jdbc):hivedb for Hive.

Response  200
HideShow
Body
[
  "schema1",
  "schema2",
  "schema3"
]

List tables
GET/projects/{projectKey}/datasets/tables-import/actions/list-tables{?connectionName}{?catalogName}{?schemaName}

List tables in a schema of a SQL connection. If schema is empty, list tables in all schemas. If catalog is empty, list tables in all catalogs (aka databases for Snowflake and projects for BigQuery). Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId until the result is ready is needed. The list elements are import candidates.


πŸ”’ Required privileges : WRITE_CONF

Example URI

GET /projects/MYPROJECT/datasets/tables-import/actions/list-tables?connectionName=?catalogName=?schemaName=
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

connectionName
string (required) 

Name of the SQL connection in which to list tables. Use @virtual(hive-jdbc):hivedb for Hive.

catalogName
string (optional) 

Name of the catalog in the SQL connection in which to list tables.

schemaName
string (optional) 

Name of the schema in the SQL connection in which to list tables.

Response  200
HideShow
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw",
  "result": [
    {
      "connectionName": "pgsql",
      "table": "my_table",
      "checked": false,
      "datasetName": "imported_from_db",
      "existingDatasetsNames": []
    }
  ]
}

Prepare import
POST/projects/{projectKey}/datasets/tables-import/actions/prepare-from-keys

Prepare the import of selected tables (SQL or Hive). Returns a reference to a future.


πŸ”’ Required privileges : WRITE_CONF

Example URI

POST /projects/MYPROJECT/datasets/tables-import/actions/prepare-from-keys
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "keys": [
    {
      "connectionName": "postgres",
      "name": "my_table"
    },
    {
      "connectionName": "@virtual(hive-jdbc):hivedb",
      "catalog": null,
      "schema": "hivedb",
      "name": "my_big_data"
    }
  ]
}
Response  200
HideShow
Body
{
  "hasResult": false,
  "aborted": false,
  "alive": false,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw"
}

Execute import
POST/projects/{projectKey}/datasets/tables-import/actions/execute-from-candidates

Perform import from a list of table candidates (SQL or Hive). Returns a reference to a future.


πŸ”’ Required privileges : WRITE_CONF

Example URI

POST /projects/MYPROJECT/datasets/tables-import/actions/execute-from-candidates
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "sqlImportCandidates": [
    {
      "connectionName": "pgsql",
      "table": "my_table",
      "checked": false,
      "datasetName": "imported_from_db",
      "existingDatasetsNames": []
    }
  ],
  "hiveImportCandidates": [
    {
      "table": "my_big_data",
      "databaseName": "hivedb",
      "connectionName": "hdfs_managed",
      "datasetName": "imported_from_hive",
      "existingDatasetsNames": [],
      "importAsHiveDataset": false,
      "isView": false
    }
  ]
}
Response  200
HideShow
Body
{
        "hasResult": false,
        "aborted": false,
        "alive": false,
        "startTime": 1561466517443,
        "runningTime": 81,
        "unknown": false,
        "jobId": "5FmUbrN3",
        "progress":
            {
                "states" [
                    {
                        "name": "Import tables",
                        "unit": "NONE",
                        "target": 4,
                        "cur": 3,
                        "important": false,
                        "depth": 9,
                        "startTimeStamp": 1561466517443,
                        "msSinceStart": 81
                    },
                    {
                        "name": "Create datasets",
                        "unit": "NONE",
                        "target": 1,
                        "cur": 0,
                        "important": false,
                        "depth": 9,
                        "startTimeStamp": 1561466517443,
                        "msSinceStart": 1
                    }
                ]
            }
    }

LLM Mesh

LLM Mesh

List available LLMs
GET/projects/{projectKey}/llms/

Lists the LLMs available in a project, including Retrieval-Augmented


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of the project

Response  200
HideShow
Headers
Content-Type: application/json
Body
[

    {
        "id": "bedrock:bedrock1:anthropic.claude-v2",
        "type": "BEDROCK",
        "connection": "bedrock1",
        "model": "anthropic.claude-v2",
        "promptDriven": True
    },
    {
        "id": "openai:openai1:gpt-4",
        "type": "OPENAI",
        "connection": "openai1",
        "model": "gpt-4",
        "promptDriven": true,
    }

    {
        "id": "huggingfacelocal:hf1:tiiuae/falcon-40b-instruct:TEXT_GENERATION_FALCON:promptDriven=true",
        "type": "HUGGINGFACE_TRANSFORMER_LOCAL",
        "connection': 'hf1",
        "model': 'tiiuae/falcon-40b-instruct",
        "promptDriven": True,
    }
]

Perform completions on a LLM
POST/projects/{projectKey}/llms/completions

Perform completions on a LLM


πŸ”’ Required privileges : READ_CONF + permissions on the LLM

Example URI

POST /projects/projectKey/llms/completions
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "llmId": "openai:openai1:gpt-4",
    "queries" : [
        {
            "messages": [
                {"role": "system", "content": "You must answer in a truthful tone"},
                {"role": "user", "content": "Who wrote Beethoven's 9th symphony?"},
            ],
            "settings": {
                "temperature": 0.9,
                "maxOutputTokens": 2048,
                "topP": 0.7
            }
        }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "responses": [
    {
      "ok": true,
      "text": "Ludwig Van Beethoven",
      "promptTokens": 42,
      "completionTokens": 5,
      "totalTokens": 47,
      "estimatedCost": 0.0000012
    }
  ]
}

Perform embeddings on a LLM
POST/projects/{projectKey}/llms/embeddings

Perform embeddings on a LLM


πŸ”’ Required privileges : READ_CONF + permissions on the LLM

Example URI

POST /projects/projectKey/llms/embeddings
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "llmId": "openai:openai1:ada002-text-embedding",
    "queries" : [
        {
            "text": "Who wrote Beethoven's 9th symphony?"
        }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "responses": [
        {
            "ok": true,
            "embedding": [0.1235243, 0.2196464, 0.365436456546]
            "promptTokens": 42,
            "estimatedCost": 0.000000012
        }
    ]
}

Dataset Statistics

Worksheets

List worksheets
GET/projects/{projectKey}/datasets/{datasetName}/statistics/worksheets/

Lists the statistics worksheets of a dataset


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/PKEY1/datasets/dataset1/statistics/worksheets/
URI Parameters
HideShow
projectKey
string (required) Example: PKEY1

Key of a project

datasetName
string (required) Example: dataset1

Name of a dataset

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "PKEY1",
    "id": "worksheet1",
    "dataSpec": {
      "inputDatasetSmartName": "dataset1",
      "datasetSelection": {
        "samplingMethod": "HEAD_SEQUENTIAL",
        "maxRecords": 30000
      }
    },
    "rootCard": {
      "type": "worksheet_root",
      "confidenceLevel": 0.95,
      "cards": []
    },
    "name": "My worksheet"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create worksheet
POST/projects/{projectKey}/datasets/{datasetName}/statistics/worksheets

Creates a new worksheet in the dataset

Important: most attributes of worksheets may be modified in future releases. It is recommended that you use the GET Worksheet call to retrieve an existing worksheet and modify it to suit your needs and create a new worksheet.


πŸ”’ Required privileges : WRITE_CONF

Example URI

POST /projects/PKEY1/datasets/dataset1/statistics/worksheets
URI Parameters
HideShow
projectKey
string (required) Example: PKEY1

Key of a project

datasetName
string (required) Example: dataset1

Name of a dataset

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "PKEY1",
  "id": "worksheet1",
  "dataSpec": {
    "inputDatasetSmartName": "dataset1",
    "datasetSelection": {
      "samplingMethod": "HEAD_SEQUENTIAL",
      "maxRecords": 30000
    }
  },
  "rootCard": {
    "type": "worksheet_root",
    "confidenceLevel": 0.95,
    "cards": []
  },
  "name": "My worksheet"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Key of the project"
    },
    "id": {
      "type": "string",
      "description": "Worksheet ID"
    },
    "name": {
      "type": "string",
      "description": "Displayed name"
    },
    "dataSpec": {
      "type": "object",
      "properties": {},
      "description": "Dataset and sampling settings"
    },
    "rootCard": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID of the card"
        },
        "type": {
          "type": "string",
          "enum": [
            "worksheet_root"
          ],
          "description": "Type of the card"
        },
        "cards": {
          "type": "string",
          "description": "Cards composing the Worksheet"
        }
      },
      "description": "Root card of the worksheet"
    }
  }
}
Response  200

Get worksheet
GET/projects/{projectKey}/datasets/{datasetName}/statistics/worksheets/{worksheetId}

Retrieves a worksheet object


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/PKEY1/datasets/dataset1/statistics/worksheets/dXs4Gy
URI Parameters
HideShow
projectKey
string (required) Example: PKEY1

Key of a project

datasetName
string (required) Example: dataset1

Name of a dataset

worksheetId
string (required) Example: dXs4Gy

ID of a worksheet

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "PKEY1",
  "id": "worksheet1",
  "dataSpec": {
    "inputDatasetSmartName": "dataset1",
    "datasetSelection": {
      "samplingMethod": "HEAD_SEQUENTIAL",
      "maxRecords": 30000
    }
  },
  "rootCard": {
    "type": "worksheet_root",
    "confidenceLevel": 0.95,
    "cards": []
  },
  "name": "My worksheet"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Key of the project"
    },
    "id": {
      "type": "string",
      "description": "Worksheet ID"
    },
    "name": {
      "type": "string",
      "description": "Displayed name"
    },
    "dataSpec": {
      "type": "object",
      "properties": {},
      "description": "Dataset and sampling settings"
    },
    "rootCard": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID of the card"
        },
        "type": {
          "type": "string",
          "enum": [
            "worksheet_root"
          ],
          "description": "Type of the card"
        },
        "cards": {
          "type": "string",
          "description": "Cards composing the Worksheet"
        }
      },
      "description": "Root card of the worksheet"
    }
  }
}

Update worksheet
PUT/projects/{projectKey}/datasets/{datasetName}/statistics/worksheets/{worksheetId}

Updates a worksheet

The worksheet object given as parameter in of a PUT call MUST have been previously obtained from a GET worksheet 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/PKEY1/datasets/dataset1/statistics/worksheets/dXs4Gy
URI Parameters
HideShow
projectKey
string (required) Example: PKEY1

Key of a project

datasetName
string (required) Example: dataset1

Name of a dataset

worksheetId
string (required) Example: dXs4Gy

ID of a worksheet

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "PKEY1",
  "id": "worksheet1",
  "dataSpec": {
    "inputDatasetSmartName": "dataset1",
    "datasetSelection": {
      "samplingMethod": "HEAD_SEQUENTIAL",
      "maxRecords": 30000
    }
  },
  "rootCard": {
    "type": "worksheet_root",
    "confidenceLevel": 0.95,
    "cards": []
  },
  "name": "My worksheet"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Key of the project"
    },
    "id": {
      "type": "string",
      "description": "Worksheet ID"
    },
    "name": {
      "type": "string",
      "description": "Displayed name"
    },
    "dataSpec": {
      "type": "object",
      "properties": {},
      "description": "Dataset and sampling settings"
    },
    "rootCard": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID of the card"
        },
        "type": {
          "type": "string",
          "enum": [
            "worksheet_root"
          ],
          "description": "Type of the card"
        },
        "cards": {
          "type": "string",
          "description": "Cards composing the Worksheet"
        }
      },
      "description": "Root card of the worksheet"
    }
  }
}
Response  200

Delete worksheet
DELETE/projects/{projectKey}/datasets/statistics/worksheets/{worksheetId}

Deletes a worksheet


πŸ”’ Required privileges : WRITE_CONF

Example URI

DELETE /projects/MYPROJECT/datasets/statistics/worksheets/dXs4Gy
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

Key of a project

worksheetId
string (required) Example: dXs4Gy

ID of a worksheet

Response  204

Actions on worksheets

Run a card
POST/projects/{projectKey}/datasets/{datasetName}/statistics/worksheets/{worksheetId}/actions/run-card

Compute a card in the context of a worksheet. The card does not necessarily need to be part of the worksheet.

Important: most attributes of cards may be modified in future releases. It is recommended that you use the GET Worksheet call to retrieve cards from an existing worksheet.

Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId until the result is ready is needed.


πŸ”’ Required privileges : READ_CONF

Example URI

POST /projects/PKEY1/datasets/dataset1/statistics/worksheets/dXs4Gy/actions/run-card
URI Parameters
HideShow
projectKey
string (required) Example: PKEY1

Key of a project

datasetName
string (required) Example: dataset1

Name of a dataset

worksheetId
string (required) Example: dXs4Gy

ID of a worksheet

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "type": "categorical_histogram",
  "maxValues": 1,
  "groupOthers": false,
  "column": {
    "name": "Embarked",
    "type": "CATEGORICAL"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "type": "categorical_histogram",
  "histogram": {
    "filters": [
      {
        "type": "anum",
        "column": "Embarked",
        "values": [
          ""
        ],
        "name": ""
      }
    ],
    "totalCount": 4,
    "counts": [
      1
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Run a computation
POST/projects/{projectKey}/datasets/{datasetName}/statistics/worksheets/{worksheetId}/actions/run-computation

Run a computation in the context of a worksheet.

Important: most attributes of computations may be modified in future releases.

Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId until the result is ready is needed.


πŸ”’ Required privileges : READ_CONF

Example URI

POST /projects/PKEY1/datasets/dataset1/statistics/worksheets/dXs4Gy/actions/run-computation
URI Parameters
HideShow
projectKey
string (required) Example: PKEY1

Key of a project

datasetName
string (required) Example: dataset1

Name of a dataset

worksheetId
string (required) Example: dXs4Gy

ID of a worksheet

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "type": "count"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "type": "count",
  "count": 890
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

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

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"
    }
  }
}

Delete scenario
DELETE/projects/{projectKey}/scenarios/{scenarioId}/

Deletes a scenario.


πŸ”’ Required privileges : WRITE_CONF

Example URI

DELETE /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
{
  "message": "Deleted scenario scenarioId from project MYPROJECT"
}

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/{projectKey}/scenarios/{scenarioId}/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/MYPROJECT/scenarios/the_scenario/get-run-for-trigger/?triggerId=?triggerRunId=
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

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": {}
}

Get a run of a trigger
GET/projects/{projectKey}/scenarios/trigger/{scenarioId}/{triggerId}{?triggerRunId}

Retrieve the details of a specific run of a trigger in the scenario.


πŸ”’ Required privileges : RUN_JOBS

Example URI

GET /projects/MYPROJECT/scenarios/trigger/the_scenario/triggerId?triggerRunId=
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

triggerId
string (required) 

identifier of the trigger

triggerRunId
string (required) 

identifier of the run of the trigger

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "scenarioId": "sId",
  "timestamp": 1506610145253,
  "trigger": {
    "delay": 0,
    "active": false,
    "type": "manual",
    "id": "manual",
    "name": "API run"
  },
  "params": {},
  "runId": "2017-09-28-16-49-05-255",
  "cancelled": false,
  "projectKey": "PKEY1"
}
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

Machine Learning - Lab

Machine Learning Lab - Analysis

This API allows you to create and manage visual analysis and create ML tasks in it, i.e. Machine Learning models

List analyses
GET/projects/{projectKey}/lab

Lists all the visual analyses of the project.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

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

the identifier of a project

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

Create a visual analysis
POST/projects/{projectKey}/lab

Create a new visual analysis


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

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

the identifier of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "analysisName": "Hello, world!",
  "inputDataset": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "analysisName": {
      "type": "string",
      "description": "Name of the visual analysis"
    },
    "inputDataset": {
      "type": "string",
      "description": "Name of the dataset used as input of the visual analysis and ML Task"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "rqlx0Vd1"
}

Get details about analysis
GET/projects/{projectKey}/lab/{analysisId}

Get all the details about a visual analysis of the project.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/lab/analysisId
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

analysisId
string (required) 

the identifier of a analysis

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "projectKey": "PROJECT",
    "id": "rqlx0Vd1",
    "inputDatasetSmartName": "my_dataset",
    "script": [...]
    "charts": [...]
    "name": "My new analysis",
    "versionTag":  {...},
    "creationTag":  {...},
    "tags": [...],
    "checklists": {...}
}

Update a visual analysis
PUT/projects/{projectKey}/lab/{analysisId}

Update a visual analysis


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

PUT /projects/projectKey/lab/analysisId
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

analysisId
string (required) 

the identifier of a analysis

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "projectKey": "PROJECT",
    "id": "rqlx0Vd1",
    "inputDatasetSmartName": "my_dataset",
    "script": [...]
    "charts": [...]
    "name": "My new analysis v2",
    "versionTag":  {...},
    "creationTag":  {...},
    "tags": [...],
    "checklists": {...}
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "Saved analysis settings for PROJECT rqlx0Vd1"
}

Delete a visual analyis
DELETE/projects/{projectKey}/lab/{analysisId}

Delete a visual analysis


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

DELETE /projects/projectKey/lab/analysisId
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

analysisId
string (required) 

the identifier of a analysis

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "Deleted analysis rqlx0Vd1 in PROJECT"
}

List ML tasks
GET/projects/{projectKey}/lab/{analysisId}/models

Get all the ML task of a visual analysis.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/lab/analysisId/models
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

analysisId
string (required) 

the identifier of a analysis

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "mlTasks": [
    {
      "analysisId": "Hello, world!",
      "mlTaskId": "Hello, world!",
      "analysisName": "Hello, world!",
      "mlTaskName": "Hello, world!",
      "taskType": "Hello, world!",
      "inputDataset": "Hello, world!"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mlTasks": {
      "type": "array",
      "description": "the references to the ML Tasks"
    }
  }
}

Create a new ML task
POST/projects/{projectKey}/lab/{analysisId}/models

Create a new visual analysis


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/lab/analysisId/models
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

analysisId
string (required) 

the identifier of a analysis

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "analysisName": "Hello, world!",
  "inputDataset": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "analysisName": {
      "type": "string",
      "description": "Name of the visual analysis"
    },
    "inputDataset": {
      "type": "string",
      "description": "Name of the dataset used as input of the visual analysis and ML Task"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "analysisId": "jSEUY6wx",
  "mlTaskId": "1xlwvos5"
}

Machine Learning Lab - ML tasks

This API allows you to create, manage, and train ML tasks, i.e. Machine Learning model labs within a DSS visual analysis.

You can manage both Prediction and Clustering ML Tasks.

List ML Tasks
GET/projects/{projectKey}/models/lab

Lists all the ML Tasks of the project (together with their containing visual analysis).


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "mlTasks": [
    {
      "analysisId": "Hello, world!",
      "mlTaskId": "Hello, world!",
      "analysisName": "Hello, world!",
      "mlTaskName": "Hello, world!",
      "taskType": "Hello, world!",
      "inputDataset": "Hello, world!"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mlTasks": {
      "type": "array",
      "description": "the references to the ML Tasks"
    }
  }
}

Create a ML Task
POST/projects/{projectKey}/models/lab

Create a new visual analysis and ML task


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/models/lab
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "analysisName": "Hello, world!",
  "inputDataset": "Hello, world!",
  "taskType": "Hello, world!",
  "predictionType": "Hello, world!",
  "targetVariable": "Hello, world!",
  "backendType": "Hello, world!",
  "sparkConfig": "Hello, world!",
  "guessPolicy": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "analysisName": {
      "type": "string",
      "description": "Name of the analysis to create"
    },
    "inputDataset": {
      "type": "string",
      "description": "Name of the input dataset"
    },
    "taskType": {
      "type": "string",
      "description": "one of PREDICTION or CLUSTERING"
    },
    "predictionType": {
      "type": "string",
      "description": "only for PREDICTION task. One of MULTICLASS, BINARY_CLASSIFICATION, REGRESSION"
    },
    "targetVariable": {
      "type": "string",
      "description": "Name of the target variable (only for PREDICTION)"
    },
    "backendType": {
      "type": "string",
      "description": "ML backend to use, one of PY_MEMORY, MLLIB or H2O"
    },
    "sparkConfig": {
      "type": "string",
      "description": "only if backend is Spark-enabled (MLLIB or H2O)"
    },
    "guessPolicy": {
      "type": "string",
      "description": "Policy to use for setting the default parameters. Valid values for prediction are: DEFAULT, SIMPLE_FORMULA, DECISION_TREE, EXPLANATORY and PERFORMANCE. Valid values for clustering are: KMEANS and ANOMALY_DETECTION"
    }
  }
}
Response  200

Machine learning lab - MLTask

Get the settings of a ML Task
GET/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/settings

Gets the settings of a single ML task.

The exact structure of the settings may vary. The Python API client can serve as reference for importing settings.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/analysisId/mlTaskId/settings
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "taskType" : "PREDICTION",
    "targetVariable" : "my_variable" /* Only for PREDICTION tasks */
    "modeling" : { /* Modeling settings */ },
    "preprocessing" : { /* Preprocessing settings */ }
    ...
}

Get the status of a ML Task
GET/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/status

Gets the status of a single ML task. The main usage of the status is to know if the MLTask is currently being guessed (initial discovery) or trained.

The exact structure of the status may vary. The Python API client can serve as reference for importing settings.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/analysisId/mlTaskId/status
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "training" : true,
    "guessing": false,
    "fullModelIds" : [
        {"id": "model1", "fullModelId" : "My-Full-opaque-id", "training" :false}
    ]
    ...
}

Re-guess a ML Task
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/guess{?predictionType}{?targetVariable}{?timeVariable}{?timeseriesIdentifiers}{?fullReguess}

Can be used to reguess all the settings of the ML task when no optional parameter are given, or (for prediction ML tasks only) to set a new value for a core parameter of the task (target variable or prediction type) and subsequently reguess the impacted settings.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/guess?predictionType=REGRESSION?targetVariable=?timeVariable=?timeseriesIdentifiers=?fullReguess=
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

analysisId
string (required) 

the identifier of a visual analysis

mlTaskId
string (required) 

the identifier of the ML task

predictionType
string (optional) Example: REGRESSION

Only valid for prediction tasks of either BINARY_CLASSIFICATION, MULTICLASS or REGRESSION type, ignored otherwise. The prediction type to set. Cannot be set if targetVariable, timeVariable or timeseriesIdentifiers is also specified.

Choices: REGRESSION BINARY_CLASSIFICATION MULTICLASS

targetVariable
string (optional) 

Only valid for prediction tasks, ignored for clustering. The target variable to set. Cannot be set if predictionType, timeVariable or timeseriesIdentifiers is also specified.

timeVariable
string (optional) 

Column to be used as time variable. Cannot be set if targetVariable, predictionType or timeseriesIdentifiers is also specified.

timeseriesIdentifiers
list of strings (optional) 

List of columns to be used as time series identifiers. Cannot be set if targetVariable, predictionType or timeVariable is also specified.

fullReguess
boolean (optional) 

Defaults to true. Scope of the reguess process: whether it should reguess all the settings after changing a core parameter, or only reguess impacted settings (e.g. target remapping when changing the target, metrics when changing the prediction type…). Ignored if no core paramater is given.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "taskType" : "PREDICTION",
    "predictionType": "REGRESSION",
    "targetVariable" : "my_variable" /* Only for PREDICTION tasks */
    "modeling" : { /* Modeling settings */ },
    "preprocessing" : { /* Preprocessing settings */ }
    ...
}

Change forecasting parameters of a time series forecasting ML Task and reguess impacted algorithm settings
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/reguess-with-forecasting-params


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/reguess-with-forecasting-params
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

analysisId
string (required) 

the identifier of a visual analysis

mlTaskId
string (required) 

the identifier of the ML task

Request
HideShow
Headers
Content-Type: application/json
Body
+ Body: forecasting parameters
    + Content 
        + forecastHorizon (number, optional) - Number of time steps within the forecast horizon
        + timestepParams (optional) - Time step parameters
            + Members
                + timeunit (string) - Valid time unit values are: `MILLISECOND`, `SECOND`, `MINUTE`, `HOUR`, `DAY`, `BUSINESS_DAY`, `WEEK`, `MONTH`, `QUARTER`, `HALF_YEAR`, `YEAR`.
                + numberOfTimeunits (number) - Number of time units within a time step.
                + endOfWeekDay (number) - The end of week day setting is only useful for the `WEEK` time unit. Valid values are: `1` (Sunday), `2` (Monday), ..., `7` (Saturday).
        + updateAlgorithmSettings (boolean, optional) - Defaults to true. Whether the algorithm settings should be reguessed after changing time step parameters.

    + Example
             {
                "forecastHorizon": "1",
                "timestepParams" : {
                    "timeunit": "DAY",
                    "numberOfTimeunits": 3,
                    "endOfWeekDay": 1
                 },
                "updateAlgorithmSettings" : true
            }
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "taskType" : "PREDICTION",
    "predictionType": "TIMESERIES_FORECASTING",
    "targetVariable" : "my_variable"
    "modeling" : { /* Modeling settings */ },
    "preprocessing" : { /* Preprocessing settings */ }
    ...
}

Start training a ML Task
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/train

Starts training a ML Task. This call returns immediately. Poll on β€œGet status” afterwards to wait for training to complete.

Request body is not mandatory.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/train
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "sessionName": "short-name",
  "sessionDescription": "longer description of this specific training session"
}
Response  204

Get the snippets of a set of trained models
GET/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models-snippets

Gets the snippets (short summary) of a set of trained models for this MLTask. The exact structure of the snippet may vary. The Python API client can serve as reference for importing settings.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/analysisId/mlTaskId/models-snippets
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "modelsIds" : [
        "id-1", /* The ids must match the fullModelIds returned by the status call */
        "id-2"
    ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id-1" : {
        /* Snippet data for model id-1 */
    },
    "id-2" : {
        /* Snippet data for model id-2 */
    }
}

Machine learning lab - Single model

Get the details of a trained model
GET/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/details

Gets the details of this trained model.

The exact structure of the status may vary. The Python API client can serve as reference for importing settings.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/details
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "trainInfo" : { ... },
    "userMeta" : { ... },
    "perf" : { ... }
    ...
}

Saves user metadata for a trained model
PUT/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/user-meta

Updates the user metadata of a model. You must only PUT the β€œuserMeta” field of a previously-retrieved model-details object.

The exact structure of the user meta may vary. The Python API client can serve as reference for importing settings.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

PUT /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/user-meta
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "name": "Name",
    "description" : "Description",
    "clusterLabels" : [ ... ],
    "tags" : ["tag1", "tag2"]   
}
Response  204

Deploy a trained model to Flow
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/actions/deployToFlow

Deploys a trained model from this ML Task to a saved model + train recipe in the Flow.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/actions/deployToFlow
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "trainDatasetRef": "Name of the train dataset to use",
  "testDatasetRef": "Name of the test dataset to use (if using EXPLICIT_EXTRACT splitting)",
  "modelName": "Name of the saved model in Flow",
  "redoOptimization": true
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "savedModelId": "identifier_of_the_new_saved_model",
  "trainRecipeName": "name_of_the_new_train_recipe"
}

Get scoring jar of a trained model
GET/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/scoring-jar{?fullClassName}{?includeLibs}

Get the scoring jar of a trained model, provided that you have the license to do so and that the model is compatible with optimized scoring.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/scoring-jar?fullClassName=model.Model?includeLibs=false
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

fullClassName
string (optional) Example: model.Model

the fully-qualified Java class name for the model

includeLibs
boolean (optional) Example: false

wether to include scoring libraries in the jar

Response  200
HideShow
Headers
Content-Type: application/java-archive

Get scoring PMML of a trained model
GET/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/scoring-pmml

Get the scoring PMML of a trained model, provided that you have the license to do so and that the model is compatible with PMML scoring.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/scoring-pmml
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Response  200
HideShow
Headers
Content-Type: application/xml

Compute subpopulation analyses of a trained model
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/subpopulation-analyses

Launch computation of subpopulation analyses for a trained model. Returns a reference to a future.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/subpopulation-analyses
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "features": ["my_col1", "my_col2"],
    "computationParams": { // optional
        "sample_size": 10000, // optional, default value is 10000
        "random_state": 1337, // optional, default value is 1337
        "n_jobs": 1, // optional, default value is 1
        "debug_mode": false, // optional, default value is false
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": false,
  "aborted": false,
  "alive": true,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw"
}

Get subpopulation analyses of a trained model
GET/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/subpopulation-analyses

Get all subpopulation analyses computed for this trained model.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/subpopulation-analyses
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    'global': { 
        'nbRecords': 10000, 
        'weightedNbRecords': 10000.0,
        'randomState': 1337,
        'onSample': true,
        'perf': { ... detailed perf ... },
        'performanceMetrics': { ... performanceMetrics ...}
    },
    'subpopulationAnalyses': [
        {
            'computed_as_type': 'CATEGORY',
            'feature': 'my_col1',
            'isDate': false,
            'sameNumRowsAsSplit': true,
            'nbRecords': 10000,
            'weightedNbRecords': 10000.0,
            'onSample': true,
            'randomState': 1337,
            'modalities': [
                {
                    'value': 'modality 1',
                    'count': 2489,
                    'weightedCount': 2489.0
                    'excluded': false,
                    'missing_values': false,
                    'perf': { ... detailed perf ... },
                    'performanceMetrics': { ... performanceMetrics ...},
                    ...
                },
                {
                    'value': 'modality 2',
                    'count': 2329,
                    'weightedCount': 2329.0
                    'excluded': true,
                    'reason': 'ONECLASS'
                    'missing_values': false,
                    ...
                },
                {
                    'value': 'modality 3',
                    'count': 1428,
                    'weightedCount': 1428.0
                    'excluded': false,
                    'missing_values': false,
                    'perf': { ... detailed perf ... },
                    'performanceMetrics': { ... performanceMetrics ...},
                    ...
                },
                ...
            ],
        },
    ]
}

Compute partial dependencies of a trained model
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/partial-dependencies

Launch computation of partial dependencies for a trained model. Returns a reference to a future.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/partial-dependencies
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "features": ["my_col1", "my_col2"],
    "computationParams": { // optional
        "sample_size": 10000, // optional, default value is 10000
        "random_state": 1337, // optional, default value is 1337
        "n_jobs": 1, // optional, default value is 1
        "debug_mode": false, // optional, default value is false
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": false,
  "aborted": false,
  "alive": true,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw"
}

Get partial dependencies of a trained model
GET/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/partial-dependencies

Get all partial dependencies computed for this trained model.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/partial-dependencies
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "partialDependencies": [
        {
            'feature': 'EDU',
            'nbRecords': 500,
            'onSample': true,
            'randomState': 1337,
            'categories': ...,
            'data': ...,
            'distribution': ...,
            ...
        },
        ...
    ]
}

Generate model documentation from default template
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/generate-documentation-from-default-template

Start the model documentation generation using the default template for this model. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated model documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/generate-documentation-from-default-template
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "template": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Generate model documentation from a custom template
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/generate-documentation-from-custom-template

Start the model documentation generation using an attached template file to upload. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated model documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/generate-documentation-from-custom-template
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

Request
HideShow
Headers
Content-Type: multipart
Body
Multipart file: the template docx file
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "template": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Generate model documentation from a template file in a managed folder
POST/projects/{projectKey}/models/lab/{analysisId}/{mlTaskId}/models/{modelFullId}/generate-documentation-from-template-in-folder{?folderId}{?path}

Start the model documentation generation using a template file in a managed folder. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated model documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/models/lab/analysisId/mlTaskId/models/modelFullId/generate-documentation-from-template-in-folder?folderId=?path=
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

analysisId
string (required) 

id of the containing visual analysis

mlTaskId
string (required) 

id of the ML task

modelFullId
string (required) 

model id as returned by the get-model-snippets call

folderId
String (required) 

the id of the managed folder

path
String (required) 

the path to the file from the root of the folder

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "template": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Download model documentation of a trained model
GET/projects/{projectKey}/models/lab/documentations/{exportId}

Download the model documentation of a trained model. The documentation exportId is obtained through a GET task call on the jobId returned when generating the model documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/models/lab/documentations/exportId
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

exportId
String (required) 

the id of the generated model documentation

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

Machine Learning - Saved models

Saved models

This API allows you to manage and get status of saved models. To create a saved model, deploy it from a ML Task.

You can manage both Prediction and Clustering Saved models.

List saved models
GET/projects/{projectKey}/savedmodels

Lists all the saved models of the project


πŸ”’ Required privileges : READ_CONF on the project

Example URI

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

The key of the project

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {
        "id" :"sq210wq2"
        "type" : "PREDICTION"
    },
    ...
]

Create saved model
POST/projects/{projectKey}/savedmodels/create-external

Creates a new saved model for storing and managing MLflow or External Models.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/savedmodels/create-external
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "savedModelType": "MLFLOW_PYFUNC", //Only 'MLFLOW_PYFUNC' or 'PROXY_MODEL' model types can be created manually.
    "predictionType": "BINARY_CLASSIFICATION", //Optional (but needed for most operations). One of 'BINARY_CLASSIFICATION', 'MULTICLASS' or 'REGRESSION'
    "name": "model" //Human readable name for the new saved model in the flow
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "projectKey": "EXPERIMENTTRACKINGMTP",
    "id": "xBVRUoqb",
    "savedModelType": "MLFLOW_PYFUNC",
    ...
}

Get saved model
GET/projects/{projectKey}/savedmodels/{savedModelId}

Get a specific saved model of the project


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id" :"sq210wq2",
    "activeVersion": "initial",
    "taskType" : "PREDICTION",
    ...
}

Update saved model
PUT/projects/{projectKey}/savedmodels/{savedModelId}

Saves the settings for a saved model.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

PUT /projects/projectKey/savedmodels/savedModelId
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "projectKey": "MLFLOWDEMO",
    "id": "u8nmwm7P",
    "savedModelType": "MLFLOW_PYFUNC", // Only 'MLFLOW_PYFUNC' model types can be created manually.
    "predictionType": "BINARY_CLASSIFICATION", //Optional (but needed for most operations). One of 'BINARY_CLASSIFICATION', 'MULTICLASS' or 'REGRESSION'
    "name": "model", //Human readable name for the new saved model in the flow,
    "contenType": "mlflow_python/prediction/py_memory",
    "activeVersion": "v02",
    "publishPolicy": "UNCONDITIONAL",
    "rebuildBehavior": "EXPLICIT",
    "conditionalOutputs": [ ... ],
    "partitioning": { ... },
    "flowOptions": { ... },
    "lastExportedFrom": "",
    "metrics": { ... },
    "metricsChecks": { ... },
    "miniTask": { ... },
    "lastTrainIndex": 1,
    "lastTrainJobId": "",
    "tags": [ ... ],
    "customFields": { ... },
    "checklists": { ... }
}
Response  204

Saved model versions

This API allows you to manage the versions of saved models.

List versions
GET/projects/{projectKey}/savedmodels/{savedModelId}/versions

Lists all versions of a saved model.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/versions
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {
        "id" : "1235012190392",
        "active" : true,
        "trainDate" : 1230944860592
    },
    ...
]

Import MLflow version from file or path
POST/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}{?codeEnvName}{?containerExecConfigName}{?folderRef}{?path}

Create a new version for this saved model from an uploaded MLflow model file or from a path containing a MLflow model in a managed folder. Requires the saved model to be created using Create saved model.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/savedmodels/savedModelId/versions/versionId?codeEnvName=?containerExecConfigName=?folderRef=?path=
URI Parameters
HideShow
projectKey
string (required) 

The key of the project.

savedModelId
string (required) 

Identifier of the saved model.

versionId
string (required) 

Version identifier.

codeEnvName
string (required) 

Name of the code env to use for this model version. The code env must contain at least mlflow and the package(s) corresponding to the used MLflow-compatible frameworks. If value is β€œINHERIT”, the code env currently defined for the project will be used.

containerExecConfigName
string (optional) 

Name of the containerized execution configuration to use while creating this model version. If value is β€œINHERIT”, the container execution configuration of the project will be used. If value is β€œNONE”, local execution will be used (no container).

folderRef
string (optional) 

Identifier of the managed folder in the form PROJECT_KEY.MANAGED_FOLDER_ID.

path
string (optional) 

Path of the MLflow folder in the managed folder.

Request
HideShow
Headers
Content-Type: multipart
Body
file (Multipart file) - MLflow model file or empty.
Response  200

Get snippet of a version
GET/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/snippet

Gets snippet (short summary) of a single version.

The exact structure of the snippet may vary. The Python API client can serve as reference for importing settings.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/versions/versionId/snippet
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    /* Snippet data  */
}

Get details of a version
GET/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/details

Gets details of a single version. The exact structure of the details may vary. The Python API client can serve as reference for importing settings.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/versions/versionId/details
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "trainInfo" : { ... },
    "userMeta" : { ... },
    "perf" : { ... }
    ...
}

Set a version as active
POST/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/actions/setActive

Sets a version as the active scoring version.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/savedmodels/savedModelId/versions/versionId/actions/setActive
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Response  204

Set a version user meta
PUT/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/user-meta

Updates the user metadata of a model version. You must only PUT the β€œuserMeta” field of a previously-retrieved model-details object.

The exact structure of the user meta may vary. The Python API client can serve as reference for importing settings.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

PUT /projects/projectKey/savedmodels/savedModelId/versions/versionId/user-meta
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "name": "Name",
    "description" : "Description",
    "clusterLabels" : [ ... ],
    "tags" : ["tag1", "tag2"]   
}
Response  204

Delete versions
GET/projects/{projectKey}/savedmodels/{savedModelId}/delete-versions{?versions}{?removeIntermediate}

Delete some versions of a saved model.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/delete-versions?versions=["1590401899705_07cf4f8f"]?removeIntermediate=true
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versions
array[string] (required) Example: ["1590401899705_07cf4f8f"]

Array of the versions to delete

removeIntermediate
boolean (optional) Example: true

Request the deletion of intermediate model versions, instantiated for each trained partition of a partitioned model. Default is true.

Response  204
HideShow
Headers
Content-Type: application/json

Get MLflow model version metadata
GET/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/external-ml/metadata

Gets metadata of a MLflow single version. The exact structure of the metadata may vary depending on the prediction type.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/versions/versionId/external-ml/metadata
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Response  200
HideShow
Body
{ 
        "importedOn": 1647351618059,
        "timeCreated": 1646980869247,
        "targetColumnName": "variety",
        "pythonCodeEnvName": "mlflow-integration-tests-base-36",
        "predictionType": "MULTICLASS",
        "classLabels": [ ... ],
        "features": [ ... ],
        "metricParams": {
            "evaluationMetric": "ROC_AUC",
            "customEvaluationMetricGIB": true,
            "customEvaluationMetricNeedsProba": false,
            "thresholdOptimizationMetric": "F1",
            "costMatrixWeights": {
                "tpGain": 1.0,
                "tnGain": 0.0,
                "fpGain": -0.3,
                "fnGain": 0.0
            },
            "liftPoint": 0.4
        },
        "flavorsLabels": [ ... ],
        "pyfuncLabels": [ ... ],
        "origin": {
            "experimentId": "QXf8VzOn",
            "runId": "2LuaCboU",
            "artifactURI": "dss-managed-folder://z7pSyYzE/QXf8VzOn/2LuaCboU/artifacts"
        }
    }

Update MLflow model version metadata
PUT/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/external-ml/metadata

Sets metadata for this MLflow model version. In addition to Β΄targetColumnNameΒ΄, one of Β΄gatherFeaturesFromDatasetΒ΄ or Β΄featuresΒ΄ must be passed in order to be able to evaluate performance.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

PUT /projects/projectKey/savedmodels/savedModelId/versions/versionId/external-ml/metadata
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Request
HideShow
Headers
Content-Type: application/json
Body
{ 
    "gatherFeaturesFromDataset": "", //Optional: Dataset reference from where to get the features.
    "importedOn": 1647351618059,
    "timeCreated": 1646980869247,
    "targetColumnName": "variety",
    "pythonCodeEnvName": "mlflow-integration-tests-base-36",
    "predictionType": "MULTICLASS",
    "classLabels": [ 
        {
            "label": "Setosa"
        }, ...
    ],
    "features": [
        {
            "name": "sepal.length",
            "type": "string"
        }, ...                    
    ],
    "metricParams": {
        "evaluationMetric": "ROC_AUC",
        "customEvaluationMetricGIB": true,
        "customEvaluationMetricNeedsProba": false,
        "thresholdOptimizationMetric": "F1",
        "costMatrixWeights": {
            "tpGain": 1.0,
            "tnGain": 0.0,
            "fpGain": -0.3,
            "fnGain": 0.0
        },
        "liftPoint": 0.4
    },
    "flavorsLabels": [ ... ],
    "pyfuncLabels": [ ... ],
    "origin": {
        "experimentId": "QXf8VzOn",
        "runId": "2LuaCboU",
        "artifactURI": "dss-managed-folder://z7pSyYzE/QXf8VzOn/2LuaCboU/artifacts"
    }
}
Response  204

Evaluate MLflow model version
POST/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/external-ml/actions/evaluate

Evaluates the performance of this model version on a particular dataset. After calling this, the β€œresult screens” of the MLflow model version will be available (confusion matrix, error distribution, performance metrics, …) and more information will be available when calling Get details of a version.


πŸ”’ Required privileges : WRITE_CONF on the project and READ_CONF on the dataset project.

Example URI

POST /projects/projectKey/savedmodels/savedModelId/versions/versionId/external-ml/actions/evaluate
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "datasetRef": "PROJECT.datasetName",
  "containerExecConfigName": "NONE"
}
Response  204

Get scoring jar of a version
GET/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/scoring-jar{?fullClassName}{?includeLibs}

Get the scoring jar of a single version, provided that you have the license to do so and that the model is compatible with optimized scoring.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/versions/versionId/scoring-jar?fullClassName=model.Model?includeLibs=false
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

fullClassName
string (optional) Example: model.Model

the fully-qualified Java class name for the model

includeLibs
boolean (optional) Example: false

wether to include scoring libraries in the jar

Response  200
HideShow
Headers
Content-Type: application/java-archive

Get scoring PMML of a version
GET/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/scoring-pmml

Get the scoring PMML of a single version, provided that you have the license to do so and that the model is compatible with PMML scoring.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/versions/versionId/scoring-pmml
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Response  200
HideShow
Headers
Content-Type: application/xml

Compute subpopulation analyses of a version
POST/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/subpopulation-analyses

Launch computation of subpopulation analyses for a version. Returns a reference to a future.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/savedmodels/savedModelId/versions/versionId/subpopulation-analyses
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "features": ["my_col1", "my_col2"],
    "computationParams": { // optional
        "sample_size": 10000, // optional, default value is 10000
        "random_state": 1337, // optional, default value is 1337
        "n_jobs": 1, // optional, default value is 1
        "debug_mode": false, // optional, default value is false
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": false,
  "aborted": false,
  "alive": true,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw"
}

Get subpopulation analyses of a version
GET/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/subpopulation-analyses

Get all subpopulation analyses computed for a version.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/versions/versionId/subpopulation-analyses
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    'global': { 
        'nbRecords': 10000, 
        'weightedNbRecords': 10000.0,
        'randomState': 1337,
        'onSample': true,
        'perf': { ... detailed perf ... },
        'performanceMetrics': { ... performanceMetrics ...}
    },
    'subpopulationAnalyses': [
        {
            'computed_as_type': 'CATEGORY',
            'feature': 'my_col1',
            'isDate': false,
            'sameNumRowsAsSplit': true,
            'nbRecords': 10000,
            'weightedNbRecords': 10000.0,
            'onSample': true,
            'randomState': 1337,
            'modalities': [
                {
                    'value': 'modality 1',
                    'count': 2489,
                    'weightedCount': 2489.0
                    'excluded': false,
                    'missing_values': false,
                    'perf': { ... detailed perf ... },
                    'performanceMetrics': { ... performanceMetrics ...},
                    ...
                },
                {
                    'value': 'modality 2',
                    'count': 2329,
                    'weightedCount': 2329.0
                    'excluded': true,
                    'reason': 'ONECLASS'
                    'missing_values': false,
                    ...
                },
                {
                    'value': 'modality 3',
                    'count': 1428,
                    'weightedCount': 1428.0
                    'excluded': false,
                    'missing_values': false,
                    'perf': { ... detailed perf ... },
                    'performanceMetrics': { ... performanceMetrics ...},
                    ...
                },
                ...
            ],
        },
    ]
}

Compute partial dependencies of a version
POST/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/partial-dependencies

Launch computation of partial dependencies for a version. Returns a reference to a future.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /projects/projectKey/savedmodels/savedModelId/versions/versionId/partial-dependencies
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "features": ["my_col1", "my_col2"],
    "computationParams": { // optional
        "sample_size": 10000, // optional, default value is 10000
        "random_state": 1337, // optional, default value is 1337
        "n_jobs": 1, // optional, default value is 1
        "debug_mode": false, // optional, default value is false
    }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": false,
  "aborted": false,
  "alive": true,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw"
}

Get partial dependencies of a version
GET/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/partial-dependencies

Get all partial dependencies computed for a version.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/savedModelId/versions/versionId/partial-dependencies
URI Parameters
HideShow
projectKey
string (required) 

The key of the project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "partialDependencies": [
        {
            'feature': 'EDU',
            'nbRecords': 500,
            'onSample': true,
            'randomState': 1337,
            'categories': ...,
            'data': ...,
            'distribution': ...,
            ...
        },
        ...
    ]
}

Generate model documentation from default template
POST/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/generate-documentation-from-default-template

Start the model documentation generation for this version using the default template for this model. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated model documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/savedmodels/savedModelId/versions/versionId/generate-documentation-from-default-template
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "exportId": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Generate model documentation from a custom template
POST/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/generate-documentation-from-custom-template

Start the model documentation generation for this version using an attached template file to upload. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated model documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/savedmodels/savedModelId/versions/versionId/generate-documentation-from-custom-template
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

Request
HideShow
Headers
Content-Type: multipart
Body
Multipart file: the template docx file
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "exportId": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Generate model documentation from a template file in a managed folder
POST/projects/{projectKey}/savedmodels/{savedModelId}/versions/{versionId}/generate-documentation-from-template-in-folder{?folderId}{?path}

Start the model documentation generation for this version using a template file in a managed folder. Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated model documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /projects/projectKey/savedmodels/savedModelId/versions/versionId/generate-documentation-from-template-in-folder?folderId=?path=
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

savedModelId
string (required) 

Identifier of the saved model

versionId
string (required) 

Version identifier

folderId
String (required) 

the id of the managed folder

path
String (required) 

the path to the file from the root of the folder

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "exportId": "gj6loGZiXw6K56KV",
    "data": {
      "messages": [],
      "anyMessage": false,
      "success": false,
      "warning": false,
      "error": false,
      "fatal": false
    }
  }
}

Download model documentation of a version
GET/projects/{projectKey}/savedmodels/documentations/{exportId}

Download the model documentation of this model version. The documentation exportId is obtained through a GET task call on the jobId returned when generating the model documentation.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /projects/projectKey/savedmodels/documentations/exportId
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

exportId
String (required) 

the id of the generated model documentation

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

Machine Learning - Experiment tracking

Experiment tracking

In order to track code-based experiments, DSS includes an integration of MLflow Tracking. DSS hosts the MLflow tracking REST API with the endpoints related to the Rest Store for the version 1.21.0. The API features additional endpoints allowing to manage experiments and models without the MLflow CLI.

When using these endpoints, the header x-dku-mlflow-project-key must be added to the request with the corresponding project key.

If calling the Create Experiment or the Create Run endpoints, it is also required to add the header x-dku-mlflow-managed-folder-id with the corresponding managed folder id in the form PROJECT_KEY.MANAGED_FOLDER_ID.

List models for a run
GET/api/2.0/mlflow/extension/models/{runId}

Returns the list of models for a given run.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

GET /api/2.0/mlflow/extension/models/runId
URI Parameters
HideShow
runId
string (required) 

The run id for which to return a list of models.

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {
        "runId": "Iw3EE0AR",
        "artifactPath": "model"
    },
    ...
]

Set inference information
POST/api/2.0/mlflow/extension/set-run-inference-info

Sets the type of the model, and optionally other information useful to deploy or evaluate it.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /api/2.0/mlflow/extension/set-run-inference-info
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "run_id": "grhZpRz2",
    "prediction_type": "MULTICLASS", // Must be one of 'BINARY_CLASSIFICATION', 'MULTICLASS', 'REGRESSION' or 'OTHER'
    "classes": "[\"Iris-setosa\", \"Iris-versicolor\", \"Iris-virginica\"]", // Optional: But mandatory in case of 'BINARY_CLASSIFICATION' or 'MULTICLASS' modes. JSON serialized ordered list of classes.
    "code_env_name": "mlflow-code-env", // Optional: name of an adequate DSS python code environment
    "target": "class" // Optional: name of the target
}
Response  204

Create virtual dataset
POST/api/2.0/mlflow/extension/create-project-experiments-dataset

Sets the type of the model, and optionally other information useful to deploy or evaluate it.


πŸ”’ Required privileges : WRITE_CONF on the project

Example URI

POST /api/2.0/mlflow/extension/create-project-experiments-dataset
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "datasetName": "dataset_name", // name of the dataset
    "experimentIds": ["FGXlefMU", "1ePQufkp"], // List of ids of experiments to filter on. No filtering if empty.
    "viewType": "ACTIVE_ONLY", // Optional: One of ACTIVE_ONLY, DELETED_ONLY and ALL. Default is ACTIVE_ONLY.
    "filter": "", // Optional: MLflow search expression.
    "orderBy": [], // Optional: List of order by clauses. Default is ordered by start_time, then runId.
    "format": "LONG" // Optional: LONG or JSON. Default is LONG.
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "value": {
        "type": "ExperimentsDB",
        "managed": true,
        "featureGroup": false,
        "name": "TEST_FROM_API",
        "projectKey": "TestAutolog",
        "checklists": { ... },
        "checks": [],
        "customMeta": { ... },
        "flowOptions": { ... },
        "readWriteOptions": { ... },
        "partitioning": { ... },
        "versionTag": { ... },
        "creationTag": { ... },
        "tags": [],
        "params": {
            "format": "LONG",
            "scope": "PROJECT",
            "projectKey": "TestAutolog",
            "experimentIds": [
                "FGXlefMU",
                "1ePQufkp"
            ],
            "viewType": "ACTIVE_ONLY",
            "filter": "",
            "orderBy": []
        },
        "schema": { ... },
        "dkuProperties": [],
        "metrics": { ... },
        "metricsChecks": { ... },
        "customFields": {}
    },
    "messages": {
        "messages": [],
        "anyMessage": false,
        "success": false,
        "warning": false,
        "error": false,
        "fatal": false
    }
}

Garbage collect
POST/api/2.0/mlflow/extension/garbage-collect

Permanently deletes the experiments and runs marked as β€œDeleted”.


πŸ”’ Required privileges : READ_CONF on the project

Example URI

POST /api/2.0/mlflow/extension/garbage-collect
Request
HideShow
Body
Empty
Response  204

Clean project
DELETE/api/2.0/mlflow/extension/clean-db/{projectKey}

Permanently deletes the experiments and runs marked as β€œDeleted”.

Note: No need to set the x-dku-mlflow-project-key header on this case.


πŸ”’ Required privileges : Admin

Example URI

DELETE /api/2.0/mlflow/extension/clean-db/projectKey
URI Parameters
HideShow
projectKey
string (required) 

The key of the project that should be cleaned up.

Request
HideShow
Body
Empty
Response  204

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/{path}

Uploads a file at the specified relative path in the folder. The file is sent as a multipart file.


πŸ”’ Required privileges : WRITE_DATA

Example URI

POST /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

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

Streaming endpoints

Streaming endpoints

List Streaming endpoints
GET/projects/{projectKey}/streamingendpoints/

Lists the streaming endpoints of a project.


πŸ”’ Required privileges : READ_CONF

Example URI

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

the identifier of a project

Response  200
HideShow

See GET streaming endpoint for more information

Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "PKEY1",
    "id": "endpoint1",
    "description": "a streaming endpoint"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create Streaming endpoint
POST/projects/{projectKey}/streamingendpoints/

Create a new streaming endpoint.

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


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the identifier of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "PKEY1",
  "id": "endpoint1",
  "type": "kafka"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this streaming endpoint"
    },
    "id": {
      "type": "string",
      "description": "Unique identifier of this streaming endpoint in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the streaming endpoint"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the connection to the data. The available parameters depend on the streaming endpoint type"
    },
    "schema": {
      "type": "object",
      "properties": {},
      "description": "Schema of this streaming endpoint"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this streaming endpoint"
    }
  }
}
Response  204

Create managed Streaming endpoint
POST/projects/{projectKey}/streamingendpoints/managed

Create a new managed streaming endpoint.


πŸ”’ Required privileges : WRITE_CONF

Example URI

POST /projects/projectKey/streamingendpoints/managed
URI Parameters
HideShow
projectKey
string (required) 

the identifier of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "endpoint1",
  "creationSettings": {
    "connectionId": "name_of_connection",
    "formatOptionId": "format_option"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this streaming endpoint"
    },
    "id": {
      "type": "string",
      "description": "Unique identifier of this streaming endpoint in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the streaming endpoint"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the connection to the data. The available parameters depend on the streaming endpoint type"
    },
    "schema": {
      "type": "object",
      "properties": {},
      "description": "Schema of this streaming endpoint"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this streaming endpoint"
    }
  }
}
Response  204

Streaming endpoint

To create a streaming endpoint see POST streamingendpoints

Get Streaming endpoint settings
GET/projects/{projectKey}/streamingendpoints/{streamingEndpointId}

Retrieves a streaming endpoint object


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of the project of the streaming endpoint

streamingEndpointId
string (required) Example: b21ed09a

the unique identifier of the streaming endpoint

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "PKEY1",
  "id": "endpoint1",
  "type": "kafka"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this streaming endpoint"
    },
    "id": {
      "type": "string",
      "description": "Unique identifier of this streaming endpoint in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the streaming endpoint"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the connection to the data. The available parameters depend on the streaming endpoint type"
    },
    "schema": {
      "type": "object",
      "properties": {},
      "description": "Schema of this streaming endpoint"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this streaming endpoint"
    }
  }
}

Update Streaming endpoint settings
PUT/projects/{projectKey}/streamingendpoints/{streamingEndpointId}

Updates the settings of a streaming endpoint.

The StreamingEndpoint object given as parameter in of a PUT call MUST have been previously obtained from a GET streamingendpoint 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.


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the key of the project of the streaming endpoint

streamingEndpointId
string (required) Example: b21ed09a

the unique identifier of the streaming endpoint

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "PKEY1",
  "id": "x97xMt4",
  "name": "folder1"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this streaming endpoint"
    },
    "id": {
      "type": "string",
      "description": "Unique identifier of this streaming endpoint in its project"
    },
    "type": {
      "type": "string",
      "description": "Type of the streaming endpoint"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Parameters of the connection to the data. The available parameters depend on the streaming endpoint type"
    },
    "schema": {
      "type": "object",
      "properties": {},
      "description": "Schema of this streaming endpoint"
    },
    "tags": {
      "type": "array",
      "description": "Tags of this streaming endpoint"
    }
  }
}
Response  204

Delete streaming endpoint
DELETE/projects/{projectKey}/streamingendpoints/{streamingEndpointId}

Deletes a streaming endpoint.

WARNING : Deleting a streaming endpoint will trigger the deletion of all associated recipes.


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the key of the project of the streaming endpoint

streamingEndpointId
string (required) Example: endpoint1

the unique identifier of the streaming endpoint

Response  204

Streaming endpoint schema

Get schema
GET/projects/{projectKey}/streamingendpoints/{streamingEndpointId}/schema

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


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/projectKey/streamingendpoints/streamingEndpointId/schema
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

streamingEndpointId
string (required) 

the unique identifier of the streaming endpoint

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}/streamingendpoints/{streamingEndpointId}/schema

The Schema object given as parameter in of a PUT call MUST have been previously obtained from a GET streamingendpoint 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 those attributes may be removed in future releases without notice.


πŸ”’ Required privileges : WRITE_SCHEMA

Example URI

PUT /projects/projectKey/streamingendpoints/streamingEndpointId/schema
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

streamingEndpointId
string (required) 

the unique identifier of the streaming endpoint

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

Continuous activities

Continuous activities

List latest continuous activities
GET/projects/{projectKey}/continuous-activities

Retrieves the list of the continuous activities, as an array of [ContinuousActivityState]


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/continuous-activities
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

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

Continuous activity

Get continuous activity status
GET/projects/{projectKey}/continuous-activities/{recipeId}

Retrieves the job status as a ContinuousActivityFullState object, giving the desired state of the continuous activity, and its actual current state.


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/continuous-activities/compute_endpoint
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

recipeId
string (required) Example: compute_endpoint

the id of a continuous activity

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "recipeType": "cpython", 
    "startedOn": 1617716549927, 
    "loopParams": {
        "abortAfterCrashes": -1, 
        "maxRestartDelayMS": 0, 
        "restartDelayIncMS": 0, 
        "initialRestartDelayMS": 0
    }, 
    "desiredState": "STARTED", 
    "recipeId": "compute_foo", 
    "mainLoopState": {
        "currentLogTail": {
            "totalLines": 54, 
            "lines": [
                "OpenJDK 64-Bit Server VM warning: ignoring option MaxPermSize=150m; support was removed in 8.0", 
                "[2021/04/06-15:42:30.951] [main] [INFO] [dku.logging]  - Loading logging settings", 
                ...
            ]
        }, 
        "futureInfo": {
            "jobDisplayName": "Runner for continuous activity STREAMS compute_foo", 
            "aborted": false, 
            "alive": true, 
            "jobId": "dQKJKzjw", 
            "hasResult": false
        }, 
        "runId": "2021-04-06-15-42-30-099", 
        "futureId": "dQKJKzjw", 
        "attemptId": "2021-04-06-15-42-30-102"
    }, 
    "startedBy": "admin", 
    "projectKey": "STREAMS"
}

Start
POST/projects/{projectKey}/continuous-activities/{recipeId}/start

Requests a new run of the specified continuous activity.


πŸ”’ Required privileges : WRITE_CONF

Example URI

POST /projects/MYPROJECT/continuous-activities/compute_endpoint/start
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

recipeId
string (required) Example: compute_endpoint

the id of a continuous activity

Response  200
HideShow
Body
{
  "aborted": false,
  "alive": true,
  "jobId": "dQKJKzjw",
  "hasResult": false,
  "startTime": 1617716666828
}

Stop
POST/projects/{projectKey}/continuous-activities/{recipeId}/stop

Stops the current run of the specified continuous activity.


πŸ”’ Required privileges : WRITE_CONF

Example URI

POST /projects/MYPROJECT/continuous-activities/compute_endpoint/stop
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

recipeId
string (required) Example: compute_endpoint

the id of a continuous activity

Response  204

Webapps

Webapps

List webapps
GET/projects/{projectKey}/webapps/

Lists the webapps in a project.


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of the project

Response  200
HideShow

Returns an array of WebappListingItem object.

Headers
Content-Type: application/json
Body
[
  {
    "backendRunning": false,
    "type": "SHINY",
    "projectKey": "VSCODEPLUGIN",
    "id": "49K1IT7",
    "name": "shiny_webapp",
    "tags": [],
    "lastModifiedBy": {
      "login": "api:ltJQh2d0JRFmMZKl",
      "displayName": "api:ltJQh2d0JRFmMZKl (deleted)"
    },
    "lastModifiedOn": 1558532240221,
    "createdBy": {
      "login": "api:ltJQh2d0JRFmMZKl",
      "displayName": "api:ltJQh2d0JRFmMZKl (deleted)"
    },
    "createdOn": 1554386952201
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Webapp

Get webapp
GET/projects/{projectKey}/webapps/{webappId}

Get a webapp


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/projectKey/webapps/webappId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

webappId
string (required) 

the id of the webapp

Response  200
HideShow

Returns Webapp object.

Headers
Content-Type: application/json
Body
{
  "type": "SHINY",
  "hasLegacyBackendURL": false,
  "projectKey": "MYPROJECT",
  "id": "49K1IT7",
  "storageFile": "projects/MYPROJECT/web_apps/49K1IT7.json",
  "params": {
    "ui": "ui code",
    "server": "server side code",
    "autoStartBackend": false,
    "envSelection": {
      "envMode": "INHERIT"
    }
  },
  "config": {},
  "name": "my_shiny_webapp",
  "versionTag": {
    "versionNumber": 15,
    "lastModifiedBy": {
      "login": "api:ltJQh2d0JRFmMZKl"
    },
    "lastModifiedOn": 1559049788289
  },
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "api:ltJQh2d0JRFmMZKl"
    },
    "lastModifiedOn": 1554386952201
  },
  "tags": [],
  "checklists": {
    "checklists": []
  },
  "customFields": {}
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this recipe"
    },
    "id": {
      "type": "string",
      "description": "Unique id of this webapp in the project"
    },
    "name": {
      "type": "string",
      "description": "Name of this webapp"
    },
    "type": {
      "type": "string",
      "description": "Type of the webapp"
    },
    "backendRunning": {
      "type": "boolean",
      "description": "Is the backend running"
    },
    "outputs": {
      "type": "object",
      "properties": {},
      "description": "Outputs of the recipe."
    },
    "tags": {
      "type": "array",
      "description": "Tags of this object"
    },
    "hasLegacyBackendURL": {
      "type": "boolean"
    },
    "storageFile": {
      "type": "string",
      "description": "Webapp file path in the DSS instance"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Depends of the webapp type"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    }
  }
}

Update webapp
PUT/projects/{projectKey}/webapps/{webappId}

Update a webapp. The Webapp object given as parameter of a PUT call MUST have been previously obtained from a GET webapp call at the same URL.


πŸ”’ Required privileges : WRITE_CONF

Example URI

PUT /projects/projectKey/webapps/webappId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

webappId
string (required) 

the id of the webapp

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "type": "SHINY",
  "hasLegacyBackendURL": false,
  "projectKey": "MYPROJECT",
  "id": "49K1IT7",
  "storageFile": "projects/MYPROJECT/web_apps/49K1IT7.json",
  "params": {
    "ui": "ui code",
    "server": "server side code",
    "autoStartBackend": false,
    "envSelection": {
      "envMode": "INHERIT"
    }
  },
  "config": {},
  "name": "my_shiny_webapp",
  "versionTag": {
    "versionNumber": 15,
    "lastModifiedBy": {
      "login": "api:ltJQh2d0JRFmMZKl"
    },
    "lastModifiedOn": 1559049788289
  },
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "api:ltJQh2d0JRFmMZKl"
    },
    "lastModifiedOn": 1554386952201
  },
  "tags": [],
  "checklists": {
    "checklists": []
  },
  "customFields": {}
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of this recipe"
    },
    "id": {
      "type": "string",
      "description": "Unique id of this webapp in the project"
    },
    "name": {
      "type": "string",
      "description": "Name of this webapp"
    },
    "type": {
      "type": "string",
      "description": "Type of the webapp"
    },
    "backendRunning": {
      "type": "boolean",
      "description": "Is the backend running"
    },
    "outputs": {
      "type": "object",
      "properties": {},
      "description": "Outputs of the recipe."
    },
    "tags": {
      "type": "array",
      "description": "Tags of this object"
    },
    "hasLegacyBackendURL": {
      "type": "boolean"
    },
    "storageFile": {
      "type": "string",
      "description": "Webapp file path in the DSS instance"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Depends of the webapp type"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    }
  }
}
Response  200
HideShow

Returns the id of the updated web app

Headers
Content-Type: application/json
Body
{
  "webAppId": "49K1IT7"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Trust a webapp
POST/projects/{projectKey}/webapps/{webappId}/actions/trust{?trustForEverybody}

Trust a webapp


πŸ”’ Required privileges : READ_CONF

Example URI

POST /projects/projectKey/webapps/webappId/actions/trust?trustForEverybody=
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

webappId
string (required) 

the id of the webapp

trustForEverybody
boolean (optional) 

trust on behalf of everybody (requires admin privileges)

Response  200
HideShow

Returns details about trust relationship between current user and the webapp.

Headers
Content-Type: application/json
Body
{
  "canAccess": true,
  "trustedCodeStatus": "TRUSTED_BY_USER"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Restart webapp backend
PUT/projects/{projectKey}/webapps/{webappId}/backend/actions/restart

Restart the webapp backend. If the backend was running, stop it and relaunch it. Returns a reference to a future.


πŸ”’ Required privileges : WRITE_CONF

Example URI

PUT /projects/projectKey/webapps/webappId/backend/actions/restart
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

webappId
string (required) 

id of the web app

Response  200
HideShow

Returns a future

Headers
Content-Type: application/json
Body
{
  "hasResult": false,
  "aborted": false,
  "alive": true,
  "startTime": 1570632529065,
  "runningTime": 0,
  "unknown": false,
  "jobId": "mEEdUTIM"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Stop webapp backend
PUT/projects/{projectKey}/webapps/{webappId}/backend/actions/stop

Stop the webapp backend.


πŸ”’ Required privileges : WRITE_CONF

Example URI

PUT /projects/projectKey/webapps/webappId/backend/actions/stop
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

webappId
string (required) 

id of the web app

Response  200

Retrieve webapp backend state
GET/projects/{projectKey}/webapps/{webappId}/backend/state

Retrieve the current backend state. If backend is not running, will only returns a JSON object with the projectKey and the webAppId.


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/projectKey/webapps/webappId/backend/state
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

webappId
string (required) 

id of the web app

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "WEBAPPS",
  "webAppId": "VCMN2ra",
  "futureId": "DGNHG1Rk",
  "futureInfo": {
    "hasResult": false,
    "aborted": false,
    "alive": true,
    "startTime": 1570700616662,
    "runningTime": 2836,
    "unknown": false,
    "jobId": "DGNHG1Rk",
    "jobDisplayName": "Backend for Web app",
    "payload": {
      "targets": [
        {
          "objectType": "WEB_APP",
          "projectKey": "WEBAPPS",
          "objectId": "VCMN2ra",
          "name": "PYTHON_BACKEND"
        }
      ],
      "displayName": "Backend for Web app",
      "extras": {
        "crashCount": 0,
        "pid": 44245
      }
    },
    "progress": {
      "states": []
    },
    "owner": "api:RINmQ0CtCiK1PjiS"
  },
  "currentLogTail": {
    "totalLines": 4,
    "lines": [
      "2019-10-10 11:43:38,736 INFO Starting Webapp backend",
      "2019-10-10 11:43:38,736 INFO Starting backend for web app: WEBAPPS.VCMN2ra",
      "2019-10-10 11:43:38,744 INFO Started backend on port 57154",
      "2019-10-10 11:43:38,935 INFO 127.0.0.1 - - [10/Oct/2019 11:43:38] \"GET /__ping HTTP/1.1\" 200 -"
    ],
    "status": [
      1,
      1,
      1,
      1
    ],
    "maxLevel": 1
  },
  "port": 57154
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Notebooks

Jupyter Notebooks

List jupyter notebook names
GET/projects/{projectKey}/jupyter-notebooks/{?active}

Lists the jupyter notebooks of a project.


πŸ”’ Required privileges : READ_CONF (on project), Create active web content

Example URI

GET /projects/projectKey/jupyter-notebooks/?active=
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

active
boolean (optional) 

Default: false. If true, only lists the jupyter notebooks that have an active session. On DSS instances configured with User Isolation (UIF), only the sessions that have been created by the current user are considered unless they are DSS administrators.

Response  200
HideShow

Returns an array of JupyterNotebookListItem objects.

Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "PROJECT_51",
    "name": "Experiment 42",
    "tags": [
      "experiment",
      "work-in-progress"
    ],
    "lastModifiedOn": 1611860176000,
    "language": "Python",
    "kernelSpec": {
      "name": "python3"
    }
  },
  {
    "projectKey": "PROJECT_51",
    "name": "john_smith's Python notebook on dataset1",
    "tags": [],
    "lastModifiedOn": 1617209410000,
    "language": "Python",
    "kernelSpec": {
      "name": "python2"
    }
  }
]

Jupyter notebook

Get jupyter notebook
GET/projects/{projectKey}/jupyter-notebooks/{notebookName}

Get a jupyter notebook


πŸ”’ Required privileges : WRITE_CONF (on project), Create active web content

Example URI

GET /projects/projectKey/jupyter-notebooks/notebookName
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

notebookName
string (required) 

the name of the notebook

Response  200
HideShow

Returns JupyterNotebook object.

Headers
Content-Type: application/json
Body
{
  "metadata": {
    "kernelspec": {
      "display_name": "Python 2",
      "name": "python2",
      "language": "python"
    },
    "language_info": {
      "mimetype": "text/x-python",
      "nbconvert_exporter": "python",
      "version": "2.7.16",
      "name": "python",
      "pygments_lexer": "ipython2",
      "file_extension": ".py",
      "codemirror_mode": {
        "version": 2,
        "name": "ipython"
      }
    },
    "tags": [],
    "modifiedBy": "john_smith",
    "createdOn": 1610719498634,
    "creator": "john_smith",
    "customFields": {
      "contains_personal_data": "UNSURE"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 1,
  "cells": [
    {
      "execution_count": 0,
      "cell_type": "code",
      "metadata": {},
      "source": [
        "1+2+3"
      ],
      "outputs": [
        {
          "output_type": "execute_result",
          "metadata": {},
          "data": {
            "text/plain": "6"
          },
          "execution_count": 2
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "properties": {},
      "description": "Notebook metadata"
    },
    "nbformat": {
      "type": "string",
      "description": "Jupyter Notebook nbformat version"
    },
    "nbformat_minor": {
      "type": "string",
      "description": "Jupyter Notebook nbformat minor version"
    },
    "cells": {
      "type": "object",
      "properties": {},
      "description": "List of the notebook cells"
    }
  }
}

Update jupyter notebook
PUT/projects/{projectKey}/jupyter-notebooks/{notebookName}

Update a jupyter notebook. The JupyterNotebook object given as parameter of a PUT call MUST have been previously obtained from a GET notebook call at the same URL.


πŸ”’ Required privileges : WRITE_CONF (on project), Run safe code, Create active web content

Example URI

PUT /projects/projectKey/jupyter-notebooks/notebookName
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

notebookName
string (required) 

the name of the notebook

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "metadata": {
    "kernelspec": {
      "display_name": "Python 2",
      "name": "python2",
      "language": "python"
    },
    "language_info": {
      "mimetype": "text/x-python",
      "nbconvert_exporter": "python",
      "version": "2.7.16",
      "name": "python",
      "pygments_lexer": "ipython2",
      "file_extension": ".py",
      "codemirror_mode": {
        "version": 2,
        "name": "ipython"
      }
    },
    "tags": [],
    "modifiedBy": "john_smith",
    "createdOn": 1610719498634,
    "creator": "john_smith",
    "customFields": {
      "contains_personal_data": "UNSURE"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 1,
  "cells": [
    {
      "execution_count": 0,
      "cell_type": "code",
      "metadata": {},
      "source": [
        "1+2+3"
      ],
      "outputs": []
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "properties": {},
      "description": "Notebook metadata"
    },
    "nbformat": {
      "type": "string",
      "description": "Jupyter Notebook nbformat version"
    },
    "nbformat_minor": {
      "type": "string",
      "description": "Jupyter Notebook nbformat minor version"
    },
    "cells": {
      "type": "object",
      "properties": {},
      "description": "List of the notebook cells"
    }
  }
}
Response  200

Create a jupyter notebook
POST/projects/{projectKey}/jupyter-notebooks/{notebookName}

Creates a new jupyter notebook, provided that you have the license do to so.

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


πŸ”’ Required privileges : WRITE_CONF (on project), Run safe code, Create active web content

Example URI

POST /projects/projectKey/jupyter-notebooks/notebookName
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

notebookName
string (required) 

the name of the notebook

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "metadata": {
    "kernelspec": {
      "display_name": "Python 2",
      "name": "python2",
      "language": "python"
    },
    "language_info": {
      "mimetype": "text/x-python",
      "nbconvert_exporter": "python",
      "version": "2.7.16",
      "name": "python",
      "pygments_lexer": "ipython2",
      "file_extension": ".py",
      "codemirror_mode": {
        "version": 2,
        "name": "ipython"
      }
    },
    "tags": [],
    "modifiedBy": "john_smith",
    "createdOn": 1610719498634,
    "creator": "john_smith",
    "customFields": {
      "contains_personal_data": "UNSURE"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 1,
  "cells": [
    {
      "execution_count": 0,
      "cell_type": "code",
      "metadata": {},
      "source": [
        "1+2+3"
      ],
      "outputs": []
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "metadata": {
      "type": "object",
      "properties": {},
      "description": "Notebook metadata"
    },
    "nbformat": {
      "type": "string",
      "description": "Jupyter Notebook nbformat version"
    },
    "nbformat_minor": {
      "type": "string",
      "description": "Jupyter Notebook nbformat minor version"
    },
    "cells": {
      "type": "object",
      "properties": {},
      "description": "List of the notebook cells"
    }
  }
}
Response  200

Delete jupyter notebook
DELETE/projects/{projectKey}/jupyter-notebooks/{notebookName}

Delete a jupyter notebook and stop all of its active sessions.


πŸ”’ Required privileges : WRITE_CONF (on project), Create active web content

Example URI

DELETE /projects/projectKey/jupyter-notebooks/notebookName
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

notebookName
string (required) 

the name of the notebook

Response  200

List jupyter notebook sessions
GET/projects/{projectKey}/jupyter-notebooks/{notebookName}/sessions

List the active sessions of a jupyter notebook.


πŸ”’ Required privileges : READ_CONF (on project), Create active web content

Example URI

GET /projects/projectKey/jupyter-notebooks/notebookName/sessions
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

notebookName
string (required) 

the name of the notebook

Response  200
HideShow

Returns an array of ActiveSession object.

Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "Hello, world!",
    "notebookName": "Hello, world!",
    "sessionsCreator": "Hello, world!",
    "sessionId": "Hello, world!",
    "kernelId": "Hello, world!",
    "kernelPid": "Hello, world!",
    "kernelConnections": "Hello, world!",
    "kernelLastActivityTime": "Hello, world!",
    "kernelExecutionState": "Hello, world!",
    "sessionStartTime": "Hello, world!"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Stop jupyter notebook session
DELETE/projects/{projectKey}/jupyter-notebooks/{notebookName}/sessions/{sessionId}

Stop the session of a jupyter notebook.

To retrieve the list of all existing sessions for a notebook, call GET notebook sessions.


πŸ”’ Required privileges : WRITE_CONF (on project), Create active web content

Example URI

DELETE /projects/projectKey/jupyter-notebooks/notebookName/sessions/sessionId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

notebookName
string (required) 

the name of the notebook

sessionId
string (required) 

the id of the session to stop

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true,
  "message": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    }
  }
}

Macros

Macros

List macros
GET/projects/{projectKey}/runnables

Retrieves the list of the last jobs, as an array of objects.


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of a project

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

Macro

Get macro definition
GET/projects/{projectKey}/runnables/{runnableType}

Retrieves the definition as a Macro object summarising the macro.


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of a project

runnableType
string (required) Example: MACRO_ID

the identifier of a macro

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "runnableType": "MACRO_ID",
  "ownerPluginId": "PLUGIN_ID",
  "meta": {
    "label": "my awesome macro"
  },
  "longDescription": "some markdown describing in detail the macro",
  "resultType": "HTML",
  "extension": "html",
  "mimeType": "application/html",
  "resultLabel": "THE RESULT",
  "params": [
    {
      "name": "param1",
      "type": "STRING"
    },
    {
      "name": "param2",
      "type": "INT"
    }
  ],
  "adminParams": []
}

Run
POST/projects/{projectKey}/runnables/{runnableType}{?wait}

Starts a run of the macro. The result contains a run identifier to pass to abort, get-result or get-status requests.


πŸ”’ Required privileges : READ_CONF

Example URI

POST /projects/MYPROJECT/runnables/MACRO_ID?wait=true
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

runnableType
string (required) Example: MACRO_ID

the identifier of a macro

wait
boolean (required) Example: true

whether the call should block until the run is finished

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "runId": "identifier_of_the_run"
}

Abort
POST/projects/{projectKey}/runnables/{runnableType}/abort/{run}

Requests the specified macro run to abort.


πŸ”’ Required privileges : READ_CONF

Example URI

POST /projects/MYPROJECT/runnables/MACRO_ID/abort/RUN_ID
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

runnableType
string (required) Example: MACRO_ID

the identifier of a macro

run
string (required) Example: RUN_ID

the identifier of the macro run

Response  204

Poll state
GET/projects/{projectKey}/runnables/{runnableType}/state/{run}

Get the status of a run of the macro. If the macro is still running, then the result of the call contains true for running, and potentially a progress field with a stack of progress info. If the run is finished but failed, either resultError or storedError will contain details on the failure; otherwise the type field will be filled.


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/runnables/MACRO_ID/state/RUN_ID
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

runnableType
string (required) Example: MACRO_ID

the identifier of a macro

run
string (required) Example: RUN_ID

the identifier of the macro run

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "exists": true,
  "running": false,
  "empty": false,
  "type": "HTML",
  "progress": {},
  "resultError": {},
  "storedError": {}
}

Retrieve result
GET/projects/{projectKey}/runnables/{runnableType}/result/{run}

Download the result of the run of the macro.


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/MYPROJECT/runnables/MACRO_ID/result/RUN_ID
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the key of a project

runnableType
string (required) Example: MACRO_ID

the identifier of a macro

run
string (required) Example: RUN_ID

the identifier of the macro run

Response  200

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
DELETE/futures/{jobId}

Abort a running task


Example URI

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

the identifier of the task

Response  200

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"
}

Upload a new plugin
POST/plugins/actions/installFromZip

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/actions/installFromZip
Request
HideShow
Headers
Content-Type: multipart
Body
Multipart file: the plugin zip file
Response  204

Installs a plugin from the store
POST/plugins/actions/installFromStore

Installs a plugin from the store. Fails if the plugin is already installed.


πŸ”’ Required privileges : ADMIN

Example URI

POST /plugins/actions/installFromStore
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "pluginId": "id of the plugin in the store"
}
Response  204

Installs a plugin from Git
POST/plugins/actions/installFromGit

Checks out a plugin from a Git repository and installs it. Fails if the plugin is already installed.

The path in the Git repository must contain at least a β€œplugin.json” file


πŸ”’ Required privileges : ADMIN

Example URI

POST /plugins/actions/installFromGit
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "gitRepositoryUrl" : "URL of a Git remote",
    "gitCheckout": "branch/tag/SHA1 to commit" /* For example, "master" */,
    "gitSubpath": "optional, path within the repository to use as Git"
}
Response  204

Plugin

Download a plugin
GET/plugins/{pluginId}/download

Downloads a development plugin as a zip file.


πŸ”’ Required privileges : ADMIN

Example URI

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

the identifier of a plugin

Response  200

Update a plugin from a Zip archive
POST/plugins/{pluginId}/actions/updateFromZip

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/actions/updateFromZip
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Request
HideShow
Headers
Content-Type: multipart
Body
Multipart file
Response  204

Update a plugin from the store
POST/plugins/{pluginId}/actions/updateFromStore

Updates a plugin from the Dataiku Store


πŸ”’ Required privileges : ADMIN

Example URI

POST /plugins/pluginId/actions/updateFromStore
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  204

Update a plugin from Git
POST/plugins/actions/updateFromGit

Checks out a plugin from a Git repository and updates it. Fails if the plugin is not already installed.

The path in the Git repository must contain at least a β€œplugin.json” file


πŸ”’ Required privileges : ADMIN

Example URI

POST /plugins/actions/updateFromGit
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "gitRepositoryUrl" : "URL of a Git remote",
    "gitCheckout": "branch/tag/SHA1 to commit" /* For example, "master" */,
    "gitSubpath": "optional, path within the repository to use as Git"
}
Response  204

Get plugin settings
GET/plugins/{pluginId}/settings

Gets the settings of a plugin


πŸ”’ Required privileges : ADMIN

Example URI

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

the identifier of a plugin

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "config" : {
        /* Dictionary of the plugins's settings parameters
    }
    "codeEnvName": "Name of the code env to use"
}

Set plugin settings
POST/plugins/{pluginId}/settings

Updates the settings of a plugin. You should only set settings that you previously obtained through the GET call


πŸ”’ Required privileges : ADMIN

Example URI

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

the identifier of a plugin

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "config" : {
        /* Dictionary of the plugins's settings parameters
    }
    "codeEnvName": "Name of the code env to use"
}
Response  204

Create the code env of a plugin
POST/plugins/{pluginId}/code-env/actions/create

Creates the code env of a plugin. Returns a reference to a future


πŸ”’ Required privileges : ADMIN

Example URI

POST /plugins/pluginId/code-env/actions/create
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "conda": false 
    "pythonInterpreter": "a Python interpreter" /* PYTHON27, PYTHON35, PYTHON36 */
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "jobId": "job id"
}

Update the code env of a plugin
POST/plugins/{pluginId}/code-env/actions/update

Updates the code env of a plugin. Returns a reference to a future


πŸ”’ Required privileges : ADMIN

Example URI

POST /plugins/pluginId/code-env/actions/update
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "jobId": "job id"
}

Move a plugin to dev environment
POST/plugins/{pluginId}/actions/moveToDev

Moves a plugin to the development environment for edition in the plugin editor.


πŸ”’ Required privileges : ADMIN

Example URI

POST /plugins/pluginId/actions/moveToDev
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  204

List usages of plugin
GET/plugins/{pluginId}/actions/listUsages{?projectKey}


πŸ”’ Required privileges : Develop plugins (if dev plugin) or ADMIN (for dev and regular plugins)

Returns information on usage of the elements of the plugin, in projects or globally.

Some custom types may not be found during usage analysis, typically when a plugin was removed but is still used. This prevents some detailed analysis and may hide some uses. This information is provided in missingTypes.

Example URI

GET /plugins/my-plugin/actions/listUsages?projectKey=MYPROJECT
URI Parameters
HideShow
pluginId
string (required) Example: my-plugin

identifier of the plugin

projectKey
string (optional) Example: MYPROJECT

if set, restrict analysis to this project

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "usages": [
        {
            "elementKind": "kind of element (webapps, python-formats,...)",
            "elementType": "type of element",
            "objectId": "id of the object using the plugin element",
            "objectType": "type of the object using the plugin element",
            "projectKey": "project key of the object using the plugin element"
        },
        ...
    ],
    "missingTypes": [
        {
            "missingType": "the missing type",
            "objectId": "id of the object depending on the missing type",
            "objectType": "type of the object depending on the missing type",
            "projectKey": "project key of the object depending on the missing type"
        },
        ...
    ]
}

Delete plugin
POST/plugins/{pluginId}/actions/delete


πŸ”’ Required privileges : Develop plugins (if dev plugin) or ADMIN (for dev and regular plugins)

Deletes a plugin. Deletion will fail if usages are detected or errors occur during usage analysis and force is not set to true.

Example URI

POST /plugins/my-plugin/actions/delete
URI Parameters
HideShow
pluginId
string (required) Example: my-plugin

identifier of the plugin

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "force": "(optional, boolean) - if true, force deletion even if usages are detected or errors occured during analysis"
}
Response  200

Development plugins

Create a new development plugins
POST/plugins/actions/createDev

Creates a new development plugin


πŸ”’ Required privileges : Develop plugins

Example URI

POST /plugins/actions/createDev
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "pluginId": "identifier of the plugin",
  "creationMode": "EMPTY or GIT_CLONE or GIT_EXPORT",
  "gitRepository": "If Git, a Git repository URL",
  "gitCheckout": "If Git, a Git checkoutable (branch, tag, hash)",
  "gitSubpath": "If GIT_EXPORT, subpath within the repositor of the plugin"
}
Response  204

Get Git remote info
GET/plugins/{pluginId}/gitRemote

Gets the information about the Git remote for this plugin.


πŸ”’ Required privileges : Develop plugins

Example URI

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

the identifier of a plugin

Response  200
HideShow
Body
{
  "repositoryUrl": "a git URL or null if no remote is declared"
}

Set Git remote info
POST/plugins/{pluginId}/gitRemote

Sets the information about the Git remote for this plugin.


πŸ”’ Required privileges : Develop plugins

Example URI

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

the identifier of a plugin

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "repositoryUrl": "a git URL"
}
Response  200

Delete Git remote info
DELETE/plugins/{pluginId}/gitRemote

Deletes the information about the Git remote for this plugin.


πŸ”’ Required privileges : Develop plugins

Example URI

DELETE /plugins/pluginId/gitRemote
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  200

List Git branches
POST/plugins/{pluginId}/gitBranches

Gets information about the Git branches for this plugin


πŸ”’ Required privileges : Develop plugins

Example URI

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

the identifier of a plugin

Response  200
HideShow
Body
[
  "branch1",
  "branch2"
]

Push to Git remote
POST/plugins/{pluginId}/actions/push

Pushes the content of a plugin to a previously-declared Git remote. The remote must have been added first in DSS.


πŸ”’ Required privileges : Develop plugins

Example URI

POST /plugins/pluginId/actions/push
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  200

Pull from Git remote
POST/plugins/{pluginId}/actions/pullRebase

Pulls (and rebases) the content of a plugin from a previously-declared Git remote. The remote must have been added first in DSS.


πŸ”’ Required privileges : Develop plugins

Example URI

POST /plugins/pluginId/actions/pullRebase
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  200

Fetch from Git remote
POST/plugins/{pluginId}/actions/fetch

Fetches the content of a plugin from a previously-declared Git remote. The remote must have been added first in DSS.


πŸ”’ Required privileges : Develop plugins

Example URI

POST /plugins/pluginId/actions/fetch
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  200

Reset to local HEAD state
POST/plugins/{pluginId}/actions/resetToLocalHeadState


πŸ”’ Required privileges : Develop plugins

Example URI

POST /plugins/pluginId/actions/resetToLocalHeadState
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Response  200

Reset to remote HEAD state
POST/plugins/{pluginId}/actions/resetToRemoteHeadState

The remote must have been added first in DSS.


πŸ”’ Required privileges : Develop plugins

Example URI

POST /plugins/pluginId/actions/resetToRemoteHeadState
URI Parameters
HideShow
pluginId
string (required) 

identifier of the plugin

Response  200

Plugin contents for dev plugins

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 : Develop plugins

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 : Develop plugins

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

Get file detail from plugin
GET/plugins/{pluginId}/details/{path}

Example URI

GET /plugins/pluginId/details/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 (can not be a folder)

Response  200
HideShow
Body
{
  "name": "my-file.py",
  "path": "folder/my-file.py",
  "mimeType": "application/octet-stream",
  "size": 10,
  "hasData": false,
  "readOnly": false,
  "lastModified": 1558532121000
}

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 : Develop plugins

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

Delete file from plugin
DELETE/plugins/{pluginId}/contents/{path}

Deletes a file from the plugin


πŸ”’ Required privileges : Develop plugins

Example URI

DELETE /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

Add folder to plugin
POST/plugins/{pluginId}/folders/{path}

Add a folder to the plugin.


πŸ”’ Required privileges : Develop plugins

Example URI

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

the identifier of a plugin

path
string (required) 

the path to the folder from the root of the plugin

Response  200

Rename file/folder in plugin
POST/plugins/{pluginId}/contents-actions/rename

Rename a file or a folder in the plugin.


πŸ”’ Required privileges : Develop plugins

Example URI

POST /plugins/pluginId/contents-actions/rename
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "oldPath": "/old/path/from/library/root"
    "newName": "new file name"
}
Response  200

Move file/folder in plugin
POST/plugins/{pluginId}/contents-actions/move

Move a file or a folder in the plugin.

The destination folder should exist prior to the call. It will not be created if it doesn’t exist.


πŸ”’ Required privileges : Develop plugins

Example URI

POST /plugins/pluginId/contents-actions/move
URI Parameters
HideShow
pluginId
string (required) 

the identifier of a plugin

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "oldPath": "/old/path/from/library/root",
  "newPath": "/new/path/from/library/root"
}
Response  200

Libraries

Libraries

List files in library
GET/projects/{projectKey}/libraries/contents/

Lists the contents in the project library


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/projectKey/libraries/contents/
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Response  200
HideShow

Returns an array of LibraryFile object.

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"
                "size": 6,
                "hasData": false,
                "lastModified": 1657102225000
             }
          ]
    },
    {
        "name": "external-libraries.json",
        "path": "external-libraries.json",
        "mimeType": "application/json",
        "size": 127,
        "hasData": false,
        "lastModified": 1657011323000
    }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Download file from library
GET/projects/{projectKey}/libraries/contents/{path}

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


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/projectKey/libraries/contents/path
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

path
string (required) 

the path to the file from the root of the library

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

Upload file to library
POST/projects/{projectKey}/libraries/contents/{path}

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


πŸ”’ Required privileges : WRITE_CONF

Warning : The file external-libraries.json is generated and modified by DSS. It is not recommended to edit it.

Example URI

POST /projects/projectKey/libraries/contents/path
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

path
string (required) 

the path to the file from the root of the library

Response  204

Delete file from library
DELETE/projects/{projectKey}/libraries/contents/{path}

Deletes a file from the library


πŸ”’ Required privileges : WRITE_CONF

Example URI

DELETE /projects/projectKey/libraries/contents/path
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

path
string (required) 

the path to the file from the root of the library

Response  204

Add folder to library
POST/projects/{projectKey}/libraries/folders/{path}

Add a folder to the library.


πŸ”’ Required privileges : WRITE_CONF

Example URI

POST /projects/projectKey/libraries/folders/path
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

path
string (required) 

the path to the folder from the root of the library

Response  200

Rename file/folder in libraries
POST/projects/{projectKey}/libraries/contents-actions/rename

Rename a file or a folder in the library.


πŸ”’ Required privileges : WRITE_CONF

Warning : The file external-libraries.json is generated and modified by DSS. It is not recommended to rename it.

Example URI

POST /projects/projectKey/libraries/contents-actions/rename
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "oldPath": "/old/path/from/library/root",
  "newName": "new name"
}
Response  200

Move file/folder in library
POST/projects/{projectKey}/libraries/contents-actions/move

Move a file or a folder in the library.

The destination folder should exist prior to the call. It will not be created if it doesn’t exist.


πŸ”’ Required privileges : WRITE_CONF

Warning : The file external-libraries.json is generated and modified by DSS. It is not recommended to move it.

Example URI

POST /projects/projectKey/libraries/contents-actions/move
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "oldPath": "/old/path/from/library/root",
  "newPath": "/new/path/from/library/root"
}
Response  200

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}

Publish package
POST/projects/{projectKey}/apiservices/{serviceId}/packages/{packageId}/publish{?publishedServiceId}

Publish an API service package to the API Deployer.


πŸ”’ Required privileges : WRITE on the published API service if it pre-exists, the global Create published API services permission on the Deployer otherwise.

Example URI

POST /projects/projectKey/apiservices/serviceId/packages/packageId/publish?publishedServiceId=
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

publishedServiceId
string (optional) 

the id of the published service where the package will be deployed (if not provided, will default to the service id)

NB If no published service with the given id is found on the API Deployer, a new one will be created using this id.

Response  200

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 : WRITE_CONF (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 : WRITE_CONF (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 : WRITE_CONF (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 : WRITE_CONF (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

Delete an exported bundle
DELETE/projects/{projectKey}/bundles/exported/

Delete an exported bundle


πŸ”’ Required privileges : WRITE_CONF (on project)

Example URI

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

the key of a project

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

Publish bundle
POST/projects/{projectKey}/bundles/{bundleId}/publish{?publishedProjectKey}

Publish a project bundle to the Project Deployer.


πŸ”’ Required privileges : WRITE on the published project if it pre-exists, the global Create published projects permission on the Deployer otherwise.

Example URI

POST /projects/projectKey/bundles/bundleId/publish?publishedProjectKey=
URI Parameters
HideShow
projectKey
string (required) 

the key of a project

bundleId
string (required) 

the id of a bundle in this project

publishedProjectKey
string (optional) 

the key of the published project where the bundle will be deployed (if not provided, will default to the project key)

NB If no published project with the given key is found on the Project Deployer, a new one will be created using this key.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "publishedOn": 1435840900000
    "publishedBy": "admin"
    "publishedProjectKey": "MYPROJECT"
}

Bundles, Automation-side

Bundles of a project

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

Retrieves the list of imported bundles for a project


πŸ”’ Required privileges : ADMIN (on project)

Example URI

GET /projects/MYPROJECT/bundles/imported
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

Preload a bundle
POST/projects/{projectKey}/bundles/imported/{bundleId}/actions/preload

Preloads a bundle, creating the necessary code environments


πŸ”’ Required privileges : ADMIN (on project)

Example URI

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

the key of a project

bundleId
string (required) Example: v1

Identifier of the bundle to preload for this project

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{?projectFolderId}

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?projectFolderId=KdLmPU6
URI Parameters
HideShow
projectFolderId
string (optional) Example: KdLmPU6

the ID of the project folder in which the new project will be created (if not provided, will defaults to root project folder)

The projectFolderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

Response  204

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

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=&projectFolderId=KdLmPU6
URI Parameters
HideShow
archivePath
string (required) 

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

projectFolderId
string (optional) Example: KdLmPU6

the ID of the project folder in which the new project will be created (if not provided, will defaults to root project folder)

The projectFolderId can be found from the get project folder API call or in the URL when accessing DSS GUI.

Response  204

Existing project

Upload a new bundle
POST/projects/{projectKey}/bundles/imported/actions/importFromStream

Uploads a bundle to an existing project. The bundle Zip content must be sent using multipart, as a β€œfile” part


πŸ”’ Required privileges : ADMIN (global)

Example URI

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

the key of a project

Response  200

Project Deployer

Deployments

List deployments
GET/project-deployer/deployments

Lists the deployments. Only the deployments on the infras for which the API key has the READ privilege, using the published projects for which the API key has READ privileges, will be listed.


πŸ”’ Required privileges : READ on the infras, READ on the published projects

Example URI

GET /project-deployer/deployments
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "projectBasicInfo": {
      "id": "MYPROJECT",
      "name": "My project",
      "versionTag": {
        "versionNumber": 15,
        "lastModifiedBy": {
          "login": "niceUser"
        },
        "lastModifiedOn": 1559049788289
      },
      "creationTag": {
        "versionNumber": 6,
        "lastModifiedBy": {
          "login": "niceUser"
        },
        "lastModifiedOn": 1554386952201
      },
      "bundleIds": [
        "bundle-v1"
      ],
      "imageInfo": {
        "objectImgHash": 1213939292,
        "isUploadedImg": false,
        "defaultImgColor": "#f44336",
        "imgColor": "#31439c",
        "imgPattern": 8
      }
    },
    "infraBasicInfo": {
      "id": "infra-id",
      "stage": "Production",
      "automationNodeUrl": "http://automation:1111",
      "defaultConnectionRemapping": [
        {
          "source": "filesystem_source",
          "target": "filesystem_target"
        }
      ],
      "governCheckPolicy": "WARN"
    },
    "deploymentBasicInfo": {
      "id": "v1-on-prod",
      "infraId": "infra-id",
      "tags": [
        "tag1"
      ],
      "creationTag": {
        "versionNumber": 6,
        "lastModifiedBy": {
          "login": "niceUser"
        },
        "lastModifiedOn": 1554386952201
      },
      "createdByDisplayName": "A nice user",
      "versionTag": {
        "versionNumber": 15,
        "lastModifiedBy": {
          "login": "niceUser"
        },
        "lastModifiedOn": 1559049788289
      },
      "lastModifiedByDisplayName": "A nicer user",
      "bundleId": "bundle-v1",
      "publishedProjectKey": "MYPROJECT",
      "deployedProjectKey": "MYAUTOMATIONPROJECT"
    },
    "packages": [
      {
        "id": "bundle-v1",
        "publishedOn": 1554386952201,
        "publishedBy": "niceUser",
        "designNodeInfo": {
          "projectKey": "MYDESIGNPROJECT",
          "nodeId": "node-id",
          "url": "http://design:1111"
        }
      }
    ],
    "neverEverDeployed": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get deployment
GET/project-deployer/deployments/{deploymentId}

Retrieves a deployment


πŸ”’ Required privileges : READ on the infra of the deployment, READ on the published project of the deployment

Example URI

GET /project-deployer/deployments/v1-on-prod
URI Parameters
HideShow
deploymentId
string (required) Example: v1-on-prod

the ID of the deployment

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "projectBasicInfo": {
    "id": "MYPROJECT",
    "name": "My project",
    "versionTag": {
      "versionNumber": 15,
      "lastModifiedBy": {
        "login": "niceUser"
      },
      "lastModifiedOn": 1559049788289
    },
    "creationTag": {
      "versionNumber": 6,
      "lastModifiedBy": {
        "login": "niceUser"
      },
      "lastModifiedOn": 1554386952201
    },
    "bundleIds": [
      "bundle-v1"
    ],
    "imageInfo": {
      "objectImgHash": 1213939292,
      "isUploadedImg": false,
      "defaultImgColor": "#f44336",
      "imgColor": "#31439c",
      "imgPattern": 8
    }
  },
  "infraBasicInfo": {
    "id": "infra-id",
    "stage": "Production",
    "automationNodeUrl": "http://automation:1111",
    "defaultConnectionRemapping": [
      {
        "source": "filesystem_source",
        "target": "filesystem_target"
      }
    ],
    "governCheckPolicy": "WARN"
  },
  "deploymentBasicInfo": {
    "id": "v1-on-prod",
    "infraId": "infra-id",
    "tags": [
      "tag1"
    ],
    "creationTag": {
      "versionNumber": 6,
      "lastModifiedBy": {
        "login": "niceUser"
      },
      "lastModifiedOn": 1554386952201
    },
    "createdByDisplayName": "A nice user",
    "versionTag": {
      "versionNumber": 15,
      "lastModifiedBy": {
        "login": "niceUser"
      },
      "lastModifiedOn": 1559049788289
    },
    "lastModifiedByDisplayName": "A nicer user",
    "bundleId": "bundle-v1",
    "publishedProjectKey": "MYPROJECT",
    "deployedProjectKey": "MYAUTOMATIONPROJECT"
  },
  "packages": [
    {
      "id": "bundle-v1",
      "publishedOn": 1554386952201,
      "publishedBy": "niceUser",
      "designNodeInfo": {
        "projectKey": "MYDESIGNPROJECT",
        "nodeId": "node-id",
        "url": "http://design:1111"
      }
    }
  ],
  "neverEverDeployed": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectBasicInfo": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the published project"
        },
        "name": {
          "type": "string",
          "description": "The name of the published project"
        },
        "creationTag": {
          "type": "object",
          "properties": {
            "versionNumber": {
              "type": "number"
            },
            "lastModifiedBy": {
              "type": "object",
              "properties": {
                "login": {
                  "type": "string"
                },
                "displayName": {
                  "type": "string"
                }
              }
            },
            "lastModifiedOn": {
              "type": "number"
            }
          },
          "description": "Creation version tag"
        },
        "versionTag": {
          "type": "object",
          "properties": {
            "versionNumber": {
              "type": "number"
            },
            "lastModifiedBy": {
              "type": "object",
              "properties": {
                "login": {
                  "type": "string"
                },
                "displayName": {
                  "type": "string"
                }
              }
            },
            "lastModifiedOn": {
              "type": "number"
            }
          },
          "description": "Current version tag"
        },
        "bundleIds": {
          "type": "array",
          "description": "A list of the IDs of the bundles uploaded on the published project"
        },
        "imageInfo": {
          "type": "string",
          "description": "A dictionary with the extended info on the project image (contains the fields objectImgHash, isUploadedImg, defaultImgColor, imgColor, showInitials, imgPattern)"
        }
      },
      "description": "Info on the published project used by the deployment"
    },
    "infraBasicInfo": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the infra"
        },
        "stage": {
          "type": "string",
          "description": "The name of the infra stage"
        },
        "automationNodeUrl": {
          "type": "string",
          "description": "URL of the Automation node"
        },
        "defaultConnectionRemapping": {
          "type": "array",
          "description": "A list of the remapping for the connections (each remapping is a dictionary containing a source and a target field)"
        },
        "governCheckPolicy": {
          "type": "string",
          "description": "The Govern check policy to prevent (PREVENT), warn (WARN) or do nothing (NO_CHECK) when the bundle is not approved in Govern"
        }
      },
      "description": "Info on the infra on which the deployment is"
    },
    "deploymentBasicInfo": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the published project"
        },
        "infraId": {
          "type": "string",
          "description": "The name of the infra where the project is deployed"
        },
        "tags": {
          "type": "array",
          "description": "The tags of the bundle used by the deployment"
        },
        "creationTag": {
          "type": "object",
          "properties": {
            "versionNumber": {
              "type": "number"
            },
            "lastModifiedBy": {
              "type": "object",
              "properties": {
                "login": {
                  "type": "string"
                },
                "displayName": {
                  "type": "string"
                }
              }
            },
            "lastModifiedOn": {
              "type": "number"
            }
          },
          "description": "Creation version tag"
        },
        "versionTag": {
          "type": "object",
          "properties": {
            "versionNumber": {
              "type": "number"
            },
            "lastModifiedBy": {
              "type": "object",
              "properties": {
                "login": {
                  "type": "string"
                },
                "displayName": {
                  "type": "string"
                }
              }
            },
            "lastModifiedOn": {
              "type": "number"
            }
          },
          "description": "Current version tag"
        },
        "createdByDisplayName": {
          "type": "string",
          "description": "The name of the user who created the deployment"
        },
        "lastModifiedByDisplayName": {
          "type": "string",
          "description": "The name of the user who did the last modification on the deployment"
        },
        "bundleId": {
          "type": "string",
          "description": "The ID of the bundle currently set for the deployment"
        },
        "publishedProjectKey": {
          "type": "string",
          "description": "The key of the published project"
        },
        "deployedProjectKey": {
          "type": "string",
          "description": "The key of the corresponding automation project"
        }
      },
      "description": "Info on the deployment"
    },
    "packages": {
      "type": "array",
      "description": "A list of the bundles available for the deployment"
    },
    "neverEverDeployed": {
      "type": "boolean",
      "description": "Whether the deployment has been deployed"
    }
  }
}

Create deployment
POST/project-deployer/deployments

Creates a deployment


πŸ”’ Required privileges : DEPLOY on the infra of the deployment, DEPLOY on the published project of the deployment

Example URI

POST /project-deployer/deployments
URI Parameters
HideShow
ignoreWarnings
boolean (optional) Example: false

ignore warnings concerning the governance status of the bundle to deploy. Default value is set to false.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "deploymentId": "v1-on-prod",
  "publishedProjectKey": "MYPROJECT",
  "infraId": "infra-id",
  "bundleId": "bundle-v1",
  "deployedProjectKey": "MYAUTOMATIONPROJECT",
  "projectFolderId": "KdLmPU6"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "v1-on-prod",
  "infraId": "infra-id",
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "versionTag": {
    "versionNumber": 15,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1559049788289
  },
  "tags": [
    "tag1"
  ],
  "publishedProjectKey": "MYPROJECT",
  "bundleId": "bundle-v1",
  "deployedProjectKey": "MYAUTOMATIONPROJECT",
  "projectFolderId": "KdLmPU6",
  "disableAutomaticTriggers": false,
  "bundleContainerSettings": {
    "remapping": {
      "connections": [
        {
          "source": "filesystem_source",
          "target": "filesystem_target"
        }
      ],
      "codeEnvs": [
        {
          "source": "codenv_source",
          "target": "codenv_target"
        }
      ]
    },
    "codeEnvsBehavior": {
      "envImportSpecificationMode": "SPECIFIED",
      "importTimeMode": "INSTALL_IF_MISS"
    }
  },
  "localVariables": {
    "k1": "v1"
  },
  "scenariosToActivate": {
    "FIRSTSCENARIO": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the deployment"
    },
    "infraId": {
      "type": "string",
      "description": "The ID of the infra"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "publishedProjectKey": {
      "type": "string",
      "description": "The key of the published project"
    },
    "bundleId": {
      "type": "string",
      "description": "The ID of the bundle"
    },
    "deployedProjectKey": {
      "type": "string",
      "description": "The key of the project on the automation node"
    },
    "projectFolderId": {
      "type": "string",
      "description": "The ID of the project folder on the automation node"
    },
    "disableAutomaticTriggers": {
      "type": "boolean",
      "description": "Whether to check the Disable automatic triggers option in the Project settings > Automation"
    },
    "bundleContainerSettings": {
      "type": "object",
      "properties": {
        "remapping": {
          "type": "object",
          "properties": {},
          "description": "A dictionary containing a list of the remapping of the connections, and a list of remapping of the code environments (each remapping is a dictionary containing a source and a target field)"
        },
        "codeEnvsBehavior": {
          "type": "object",
          "properties": {},
          "description": "A dictionary containing the package list source (field envImportSpecificationMode, can be either SPECIFIED or ACTUAL) and the environment import mode (field importTimeMode, can be either INSTALL_IF_MISS, FAIL_IF_MISS or DO_NOTHING)"
        }
      },
      "description": "Remapping and code environments settings"
    },
    "localVariables": {
      "type": "object",
      "properties": {},
      "description": "A dictionary of the local project variables"
    },
    "scenariosToActivate": {
      "type": "object",
      "properties": {},
      "description": "Mapping of scenario ID (string) -> whether to activate the auto-triggers of the scenario (boolean)"
    }
  }
}

Delete deployment
DELETE/project-deployer/deployments/{deploymentId}

Deletes a deployment


πŸ”’ Required privileges : DEPLOY on the infra of the deployment, DEPLOY on the published project of the deployment

Example URI

DELETE /project-deployer/deployments/v1-on-prod
URI Parameters
HideShow
deploymentId
string (required) Example: v1-on-prod

the ID of the deployment

Response  204

Get deployment settings
GET/project-deployer/deployments/{deploymentId}/settings

Retrieves the settings of a deployment


πŸ”’ Required privileges : READ on the infra of the deployment, READ on the published project of the deployment

Example URI

GET /project-deployer/deployments/v1-on-prod/settings
URI Parameters
HideShow
deploymentId
string (required) Example: v1-on-prod

the ID of the deployment

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "v1-on-prod",
  "infraId": "infra-id",
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "versionTag": {
    "versionNumber": 15,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1559049788289
  },
  "tags": [
    "tag1"
  ],
  "publishedProjectKey": "MYPROJECT",
  "bundleId": "bundle-v1",
  "deployedProjectKey": "MYAUTOMATIONPROJECT",
  "projectFolderId": "KdLmPU6",
  "disableAutomaticTriggers": false,
  "bundleContainerSettings": {
    "remapping": {
      "connections": [
        {
          "source": "filesystem_source",
          "target": "filesystem_target"
        }
      ],
      "codeEnvs": [
        {
          "source": "codenv_source",
          "target": "codenv_target"
        }
      ]
    },
    "codeEnvsBehavior": {
      "envImportSpecificationMode": "SPECIFIED",
      "importTimeMode": "INSTALL_IF_MISS"
    }
  },
  "localVariables": {
    "k1": "v1"
  },
  "scenariosToActivate": {
    "FIRSTSCENARIO": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the deployment"
    },
    "infraId": {
      "type": "string",
      "description": "The ID of the infra"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "publishedProjectKey": {
      "type": "string",
      "description": "The key of the published project"
    },
    "bundleId": {
      "type": "string",
      "description": "The ID of the bundle"
    },
    "deployedProjectKey": {
      "type": "string",
      "description": "The key of the project on the automation node"
    },
    "projectFolderId": {
      "type": "string",
      "description": "The ID of the project folder on the automation node"
    },
    "disableAutomaticTriggers": {
      "type": "boolean",
      "description": "Whether to check the Disable automatic triggers option in the Project settings > Automation"
    },
    "bundleContainerSettings": {
      "type": "object",
      "properties": {
        "remapping": {
          "type": "object",
          "properties": {},
          "description": "A dictionary containing a list of the remapping of the connections, and a list of remapping of the code environments (each remapping is a dictionary containing a source and a target field)"
        },
        "codeEnvsBehavior": {
          "type": "object",
          "properties": {},
          "description": "A dictionary containing the package list source (field envImportSpecificationMode, can be either SPECIFIED or ACTUAL) and the environment import mode (field importTimeMode, can be either INSTALL_IF_MISS, FAIL_IF_MISS or DO_NOTHING)"
        }
      },
      "description": "Remapping and code environments settings"
    },
    "localVariables": {
      "type": "object",
      "properties": {},
      "description": "A dictionary of the local project variables"
    },
    "scenariosToActivate": {
      "type": "object",
      "properties": {},
      "description": "Mapping of scenario ID (string) -> whether to activate the auto-triggers of the scenario (boolean)"
    }
  }
}

Save deployment settings
PUT/project-deployer/deployments/{deploymentId}/settings

Saves the settings of a deployment. You should first retrieve the current settings with a GET call.


πŸ”’ Required privileges : DEPLOY on the infra of the deployment, DEPLOY on the published project of the deployment

Example URI

PUT /project-deployer/deployments/v1-on-prod/settings
URI Parameters
HideShow
deploymentId
string (required) Example: v1-on-prod

the ID of the deployment

ignoreWarnings
boolean (optional) Example: false

ignore warnings concerning the governance status of the bundle to deploy. Default value is set to false.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "v1-on-prod",
  "infraId": "infra-id",
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "versionTag": {
    "versionNumber": 15,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1559049788289
  },
  "tags": [
    "tag1"
  ],
  "publishedProjectKey": "MYPROJECT",
  "bundleId": "bundle-v1",
  "deployedProjectKey": "MYAUTOMATIONPROJECT",
  "projectFolderId": "KdLmPU6",
  "disableAutomaticTriggers": false,
  "bundleContainerSettings": {
    "remapping": {
      "connections": [
        {
          "source": "filesystem_source",
          "target": "filesystem_target"
        }
      ],
      "codeEnvs": [
        {
          "source": "codenv_source",
          "target": "codenv_target"
        }
      ]
    },
    "codeEnvsBehavior": {
      "envImportSpecificationMode": "SPECIFIED",
      "importTimeMode": "INSTALL_IF_MISS"
    }
  },
  "localVariables": {
    "k1": "v1"
  },
  "scenariosToActivate": {
    "FIRSTSCENARIO": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the deployment"
    },
    "infraId": {
      "type": "string",
      "description": "The ID of the infra"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "publishedProjectKey": {
      "type": "string",
      "description": "The key of the published project"
    },
    "bundleId": {
      "type": "string",
      "description": "The ID of the bundle"
    },
    "deployedProjectKey": {
      "type": "string",
      "description": "The key of the project on the automation node"
    },
    "projectFolderId": {
      "type": "string",
      "description": "The ID of the project folder on the automation node"
    },
    "disableAutomaticTriggers": {
      "type": "boolean",
      "description": "Whether to check the Disable automatic triggers option in the Project settings > Automation"
    },
    "bundleContainerSettings": {
      "type": "object",
      "properties": {
        "remapping": {
          "type": "object",
          "properties": {},
          "description": "A dictionary containing a list of the remapping of the connections, and a list of remapping of the code environments (each remapping is a dictionary containing a source and a target field)"
        },
        "codeEnvsBehavior": {
          "type": "object",
          "properties": {},
          "description": "A dictionary containing the package list source (field envImportSpecificationMode, can be either SPECIFIED or ACTUAL) and the environment import mode (field importTimeMode, can be either INSTALL_IF_MISS, FAIL_IF_MISS or DO_NOTHING)"
        }
      },
      "description": "Remapping and code environments settings"
    },
    "localVariables": {
      "type": "object",
      "properties": {},
      "description": "A dictionary of the local project variables"
    },
    "scenariosToActivate": {
      "type": "object",
      "properties": {},
      "description": "Mapping of scenario ID (string) -> whether to activate the auto-triggers of the scenario (boolean)"
    }
  }
}
Response  204

Get deployment status
GET/project-deployer/deployments/{deploymentId}/status

Retrieves a Project deployment status


πŸ”’ Required privileges : READ on the infra of the deployment, READ on the published project of the deployment

Example URI

GET /project-deployer/deployments/v1-on-prod/status
URI Parameters
HideShow
deploymentId
string (required) Example: v1-on-prod

the ID of the deployment

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "healthMessages": [],
    /* Can be one of UNKNOWN, ERROR, WARNING, HEALTHY, OUT_OF_SYNC */
    "health": "HEALTHY",
    "deploymentId": "v1-on-prod";,
    "monitoring": {
        "failed": [],
        "warning": ["scenario-2"],
        "successful": ["scenario-1"],
        "aborted": [],
        "running": []
    }
    "hasScenarios": true,
    "hasActiveScenarios": false
}

Get governance deployment status
GET/project-deployer/deployments/{deploymentId}/governance-status

Retrieves the governance status of the bundle used in this deployment


πŸ”’ Required privileges : READ on the infra of the deployment, READ on the published project of the deployment

Example URI

GET /project-deployer/deployments/v1-on-prod/governance-status
URI Parameters
HideShow
deploymentId
string (required) Example: v1-on-prod

the ID of the deployment

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": [
    {
      "severity": "WARNING",
      "isFatal": false,
      "code": "ERR_DEPLOYER_INVALID_GOVERNANCE_STATUS",
      "title": "Invalid governance status",
      "details": "The bundle should be approved before being deployed to this infrastructure, but  bundle \"bundleId\" is not governed.",
      "message": "Invalid governance status: The bundle should be approved before being deployed to this infrastructure, but  bundle \"bundleId\" is not governed.",
      "governLink": "https://govern-inst:4200/artifact/ar.207"
    }
  ],
  "maxSeverity": "WARNING",
  "anyMessage": true,
  "success": false,
  "warning": true,
  "error": false,
  "fatal": false
}

Update deployment
POST/project-deployer/deployments/{deploymentId}/actions/update

Updates a deployment. If the update is done asynchronously (see the request body), this call returns a reference to a future (defined by its jobId). If the future has no result yet, one needs to poll on the jobId until the result is ready.


πŸ”’ Required privileges : DEPLOY on the infra of the deployment, DEPLOY on the published project of the deployment

Example URI

POST /project-deployer/deployments/v1-on-prod/actions/update
URI Parameters
HideShow
deploymentId
string (required) Example: v1-on-prod

the ID of the deployment

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "synchronous": true
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw",
  "result": [
    {
      "prepareSyncReport": {
        "messages": [],
        "anyMessage": false,
        "success": false,
        "warning": false,
        "error": false,
        "fatal": false
      },
      "preloadReport": {
        "messages": [],
        "anyMessage": false,
        "success": false,
        "warning": false,
        "error": false,
        "fatal": false
      },
      "activateCheckReport": {
        "bundleId": "bundle-v1",
        "messages": [],
        "anyMessage": false,
        "success": false,
        "warning": false,
        "error": false,
        "fatal": false
      },
      "activateReport": {
        "neededAMigration": false,
        "messages": [],
        "anyMessage": false,
        "success": false,
        "warning": false,
        "error": false,
        "fatal": false
      }
    }
  ]
}

Published projects

List projects
GET/project-deployer/projects

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


πŸ”’ Required privileges : READ on each published project

Example URI

GET /project-deployer/projects
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {
        "projectBasicInfo": {
            "id": "MYPROJECT",
            "name": "My project",
            "versionTag": {
                "versionNumber": 15,
                "lastModifiedBy": {
                    "login": "niceUser"
                },
                "lastModifiedOn": 1559049788289
            },
            "creationTag": {
                "versionNumber": 6,
                "lastModifiedBy": {
                    "login": "niceUser"
                },
                "lastModifiedOn": 1554386952201
            },
            "bundleIds": ["bundle-v1"],
            "imageInfo": {
                "objectImgHash": 1213939292,
                "isUploadedImg": false,
                "defaultImgColor": "#f44336",
                "imgColor": "#31439c",
                "imgPattern": 8
            }
        },
        "packages": [
            {
                "id": "bundle-v1",
                "publishedOn": 1554386952201,
                "publishedBy": "niceUser",
                "designNodeInfo": {
                    "projectKey": "MYDESIGNPROJECT",
                    "nodeId": "node-id",
                    "url": "http://design:1111"
                }
            }
        ],
        "deployments": [
            {
                "id": "v1-on-prod",
                "infraId": "infra-id",
                "tags": ["tag1"],
                "creationTag": {
                    "versionNumber": 6,
                    "lastModifiedBy": {
                        "login": "niceUser"
                    },
                    "lastModifiedOn": 1554386952201
                },
                "createdByDisplayName": "A nice user",
                "versionTag": {
                    "versionNumber": 15,
                    "lastModifiedBy": {
                        "login": "niceUser"
                    },
                    "lastModifiedOn": 1559049788289
                },
                "lastModifiedByDisplayName": "A nicer user",
            }
        ],
        "infras": [
            {
                "id": "infra-id",
                "stage": "Production",
                "automationNodeUrl": "http://automation:1111",
                "defaultConnectionRemapping": [
                    {
                        "source": "filesystem_source",
                        "target": "filesystem_target"
                    }
                ]
            }
        ],
        "isAdmin": false,
        "canDeploy": true,
        "canWrite": true
    }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get project
GET/project-deployer/projects/{projectKey}

Retrieves a published projects.


πŸ”’ Required privileges : READ on the published project

Example URI

GET /project-deployer/projects/MYPROJECT
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the project key

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "projectBasicInfo": {
        "id": "MYPROJECT",
        "name": "My project",
        "versionTag": {
            "versionNumber": 15,
            "lastModifiedBy": {
                "login": "niceUser"
            },
            "lastModifiedOn": 1559049788289
        },
        "creationTag": {
            "versionNumber": 6,
            "lastModifiedBy": {
                "login": "niceUser"
            },
            "lastModifiedOn": 1554386952201
        },
        "bundleIds": ["bundle-v1"],
        "imageInfo": {
            "objectImgHash": 1213939292,
            "isUploadedImg": false,
            "defaultImgColor": "#f44336",
            "imgColor": "#31439c",
            "imgPattern": 8
        }
    },
    "packages": [
        {
            "id": "bundle-v1",
            "publishedOn": 1554386952201,
            "publishedBy": "niceUser",
            "designNodeInfo": {
                "projectKey": "MYDESIGNPROJECT"
                "nodeId": "node-id"
                "url": "http://design:1111"
            }
        }
    ],
    "deployments": [
        {
            "id": "v1-on-prod",
            "infraId": "infra-id",
            "tags": ["tag1"],
            "creationTag": {
                "versionNumber": 6,
                "lastModifiedBy": {
                    "login": "niceUser"
                },
                "lastModifiedOn": 1554386952201
            },
            "createdByDisplayName": "A nice user",
            "versionTag": {
                "versionNumber": 15,
                "lastModifiedBy": {
                    "login": "niceUser"
                },
                "lastModifiedOn": 1559049788289
            },
            "lastModifiedByDisplayName": "A nicer user",
        }
    ],
    "infras": [
        {
            "id": "infra-id",
            "stage": "Production",
            "automationNodeUrl": "http://automation:1111",
            "defaultConnectionRemapping": [
                {
                    "source": "filesystem_source",
                    "target": "filesystem_target"
                }
            ]
        }
    ],
    "isAdmin": false,
    "canDeploy": true,
    "canWrite": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectBasicInfo": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the published project"
        },
        "name": {
          "type": "string",
          "description": "The name of the published project"
        },
        "creationTag": {
          "type": "object",
          "properties": {
            "versionNumber": {
              "type": "number"
            },
            "lastModifiedBy": {
              "type": "object",
              "properties": {
                "login": {
                  "type": "string"
                },
                "displayName": {
                  "type": "string"
                }
              }
            },
            "lastModifiedOn": {
              "type": "number"
            }
          },
          "description": "Creation version tag"
        },
        "versionTag": {
          "type": "object",
          "properties": {
            "versionNumber": {
              "type": "number"
            },
            "lastModifiedBy": {
              "type": "object",
              "properties": {
                "login": {
                  "type": "string"
                },
                "displayName": {
                  "type": "string"
                }
              }
            },
            "lastModifiedOn": {
              "type": "number"
            }
          },
          "description": "Current version tag"
        },
        "bundleIds": {
          "type": "array",
          "description": "A list of the IDs of the bundles uploaded on the published project"
        },
        "imageInfo": {
          "type": "string",
          "description": "A dictionary with the extended info on the project image (contains the fields objectImgHash, isUploadedImg, defaultImgColor, imgColor, showInitials, imgPattern)"
        }
      },
      "description": "Info on the published project"
    },
    "packages": {
      "type": "array",
      "description": "A list of the bundles uploaded on the published project"
    },
    "deployments": {
      "type": "array",
      "description": "A list of the deployments using the published project"
    },
    "infras": {
      "type": "array",
      "description": "A list of the Automation infrastructures where the published project is deployed"
    },
    "isAdmin": {
      "type": "boolean",
      "description": "Whether the user who made the request has admin rights on the published project"
    },
    "canDeploy": {
      "type": "boolean",
      "description": "Whether the user who made the request has deploying rights on the published project"
    },
    "canWrite": {
      "type": "boolean",
      "description": "Whether the user who made the request has writing rights on the published project"
    }
  }
}

Create project
POST/project-deployer/projects

Creates a published project.


πŸ”’ Required privileges : User has the mayCreatePublishedProjects global permission.

Example URI

POST /project-deployer/projects
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "publishedProjectKey": "MYPROJECT"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "MYPROJECT",
  "name": "MYPROJECT",
  "permissions": [
    {
      "group": "data_scientists",
      "read": true,
      "write": true,
      "deploy": true,
      "admin": false
    }
  ],
  "owner": "niceUser",
  "versionTag": {
    "versionNumber": 15,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1559049788289
  },
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "basicImageInfo": {
    "imgColor": "#31439c",
    "imgPattern": 8,
    "showInitials": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the published project"
    },
    "name": {
      "type": "string",
      "description": "The name of the published project"
    },
    "permissions": {
      "type": "array",
      "description": "A list of permission dictionaries for user groups (permissions being read, write, deploy, admin)"
    },
    "owner": {
      "type": "string",
      "description": "ID of the published project owner"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    },
    "basicImageInfo": {
      "type": "object",
      "properties": {},
      "description": "A dictionary with the info regarding the color pattern used as the project image, not relevant if the project uses an uploaded image (contains the fields imgColor, showInitials, imgPattern)"
    }
  }
}

Delete project
DELETE/project-deployer/projects/{projectKey}

Deletes the published project. Only published projects not currently used in any deployments can be deleted.


πŸ”’ Required privileges : ADMIN on the published project

Example URI

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

the project key

Response  204

Get project settings
GET/project-deployer/projects/settings

Gets the settings of the published project.


πŸ”’ Required privileges : ADMIN on the published project

Example URI

GET /project-deployer/projects/settings
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "MYPROJECT",
  "name": "MYPROJECT",
  "permissions": [
    {
      "group": "data_scientists",
      "read": true,
      "write": true,
      "deploy": true,
      "admin": false
    }
  ],
  "owner": "niceUser",
  "versionTag": {
    "versionNumber": 15,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1559049788289
  },
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "basicImageInfo": {
    "imgColor": "#31439c",
    "imgPattern": 8,
    "showInitials": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the published project"
    },
    "name": {
      "type": "string",
      "description": "The name of the published project"
    },
    "permissions": {
      "type": "array",
      "description": "A list of permission dictionaries for user groups (permissions being read, write, deploy, admin)"
    },
    "owner": {
      "type": "string",
      "description": "ID of the published project owner"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    },
    "basicImageInfo": {
      "type": "object",
      "properties": {},
      "description": "A dictionary with the info regarding the color pattern used as the project image, not relevant if the project uses an uploaded image (contains the fields imgColor, showInitials, imgPattern)"
    }
  }
}

Save project settings
PUT/project-deployer/projects/{projectKey}/settings

Saves the settings of the published project. You should first retrieve the current settings with a GET call.


πŸ”’ Required privileges : ADMIN on the published project

Example URI

PUT /project-deployer/projects/MYPROJECT/settings
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the project key

Request
HideShow
Headers
Content-Type: PublishedProject
Body
{
  "id": "MYPROJECT",
  "name": "MYPROJECT",
  "permissions": [
    {
      "group": "data_scientists",
      "read": true,
      "write": true,
      "deploy": true,
      "admin": false
    }
  ],
  "owner": "niceUser",
  "versionTag": {
    "versionNumber": 15,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1559049788289
  },
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "basicImageInfo": {
    "imgColor": "#31439c",
    "imgPattern": 8,
    "showInitials": true
  }
}
Response  204

Upload bundle
POST/project-deployer/projects/bundles{?projectKey}{?filePart}

Uploads a bundle on the Deployer. If no project key is provided, the key of the bundle’s source project is used


πŸ”’ Required privileges : WRITE on the published project

Example URI

POST /project-deployer/projects/bundles?projectKey=MYPROJECT?filePart=/home/data/import/bundle-v1.zip
URI Parameters
HideShow
projectKey
string (optional) Example: MYPROJECT

the key of the project where the bundle is uploaded. If no published project matches this key, it is created

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

the absolute path where the bundle resides

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "bundle-v1",
  "publishedOn": 1554386952201,
  "publishedBy": "niceUser",
  "designNodeInfo": {
    "projectKey": "MYDESIGNPROJECT",
    "nodeId": "node-id",
    "url": "http://design:1111"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The bundle ID"
    },
    "publishedOn": {
      "type": "number",
      "description": "Timestamp for the publish date"
    },
    "publishedBy": {
      "type": "string",
      "description": "ID of the publish user"
    },
    "designNodeInfo": {
      "type": "object",
      "properties": {},
      "description": "Info on the bundle's Design project of origin (contains the fields projectKey, nodeId, url)"
    }
  }
}

Delete bundle
DELETE/project-deployer/projects/{projectKey}/bundles/{bundleId}

Deletes a bundle. Only bundles not currently used in any deployments can be deleted.


πŸ”’ Required privileges : WRITE on the published project

Example URI

DELETE /project-deployer/projects/MYPROJECT/bundles/bundle-v1
URI Parameters
HideShow
projectKey
string (required) Example: MYPROJECT

the project key where the bundle is

bundleId
string (required) Example: bundle-v1

the ID of the bundle to delete

Response  204

Infrastructures

List stages
GET/project-deployer/infras/stages

Lists the Project Deployer stages.


Example URI

GET /project-deployer/infras/stages
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "Development",
    "desc": "For applications development"
  },
  {
    "id": "Test",
    "desc": "Acceptance testing"
  },
  {
    "id": "Production",
    "desc": "Running live for users"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

List infras
GET/project-deployer/infras

Lists the Automation infras on the Deployer. Only the infras for which the API key has the READ privilege will be listed.


πŸ”’ Required privileges : READ on each infra

Example URI

GET /project-deployer/infras
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {
        "infraBasicInfo": {
            "id": "infra-id",
            "stage": "Production",
            "automationNodeUrl": "http://automation:1111",
            "defaultConnectionRemapping": [
                {
                    "source": "filesystem_source",
                    "target": "filesystem_target"
                }
            ],
            "governCheckPolicy": "WARN"
        },
        "deployments": [
            {
                "id": "v1-on-prod",
                "infraId": "infra-id",
                "tags": ["tag1"],
                "creationTag": {
                    "versionNumber": 6,
                    "lastModifiedBy": {
                        "login": "niceUser"
                    },
                    "lastModifiedOn": 1554386952201
                },
                "createdByDisplayName": "A nice user",
                "versionTag": {
                    "versionNumber": 15,
                    "lastModifiedBy": {
                        "login": "niceUser"
                    },
                    "lastModifiedOn": 1559049788289
                },
                "lastModifiedByDisplayName": "A nicer user",
            }
        ],
        "isAdmin": false,
        "canDeploy": true
    }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get infra
GET/project-deployer/infras/{infraId}

Gets an Automation infra on the Deployer.


πŸ”’ Required privileges : READ on the infra

Example URI

GET /project-deployer/infras/infra-id
URI Parameters
HideShow
infraId
string (required) Example: infra-id

the ID of the infra

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
        "infraBasicInfo": {
            "id": "infra-id",
            "stage": "Production",
            "automationNodeUrl": "http://automation:1111",
            "defaultConnectionRemapping": [
                {
                    "source": "filesystem_source",
                    "target": "filesystem_target"
                }
            ],    
            "governCheckPolicy": "WARN"
        },
        "deployments": [
            {
                "id": "v1-on-prod",
                "infraId": "infra-id",
                "tags": ["tag1"],
                "creationTag": {
                    "versionNumber": 6,
                    "lastModifiedBy": {
                        "login": "niceUser"
                    },
                    "lastModifiedOn": 1554386952201
                },
                "createdByDisplayName": "A nice user",
                "versionTag": {
                    "versionNumber": 15,
                    "lastModifiedBy": {
                        "login": "niceUser"
                    },
                    "lastModifiedOn": 1559049788289
                },
                "lastModifiedByDisplayName": "A nicer user",
            }
        ],
        "isAdmin": false,
        "canDeploy": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "infraBasicInfo": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the infra"
        },
        "stage": {
          "type": "string",
          "description": "The name of the infra stage"
        },
        "automationNodeUrl": {
          "type": "string",
          "description": "URL of the Automation node"
        },
        "defaultConnectionRemapping": {
          "type": "array",
          "description": "A list of the remapping for the connections (each remapping is a dictionary containing a source and a target field)"
        },
        "governCheckPolicy": {
          "type": "string",
          "description": "The Govern check policy to prevent (PREVENT), warn (WARN) or do nothing (NO_CHECK) when the bundle is not approved in Govern"
        }
      },
      "description": "Info on the Automation infra"
    },
    "deployments": {
      "type": "array",
      "description": "A list of the deployments on the Automation infra"
    },
    "isAdmin": {
      "type": "boolean",
      "description": "Whether the user who made the request has admin rights on the Automation infra"
    },
    "canDeploy": {
      "type": "boolean",
      "description": "Whether the user who made the request has deploying rights on the Automation infra"
    }
  }
}

Create infra
POST/project-deployer/projects/infras

Creates an Automation infra on the Deployer.


πŸ”’ Required privileges : ADMIN of the Deployer node

Example URI

POST /project-deployer/projects/infras
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "infra-id",
  "stage": "Production",
  "automationNodeUrl": "http://automation:1111",
  "apiKey": "tl1cba6Dy3uZCVy0q1RgtDFcGvCO5Nfh",
  "governCheckPolicy": "WARN"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "infra-id",
  "permissions": [
    {
      "group": "data_scientists",
      "read": true,
      "deploy": true,
      "admin": false
    }
  ],
  "versionTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "autoconfigureFromNodesDirectory": false,
  "nodeId": "node-id",
  "automationNodeUrl": "http://automation:1111",
  "adminApiKey": "tl1cba6Dy3uZCVy0q1RgtDFcGvCO5Nfh",
  "trustAllSSLCertificates": true,
  "governCheckPolicy": "WARN"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the infra"
    },
    "permissions": {
      "type": "array",
      "description": "A list of permission dictionaries for user groups (permissions being read, deploy, admin)"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "autoconfigureFromNodesDirectory": {
      "type": "boolean"
    },
    "nodeId": {
      "type": "string",
      "description": "ID of the Automation node"
    },
    "automationNodeUrl": {
      "type": "string",
      "description": "URL of the Automation node"
    },
    "adminApiKey": {
      "type": "string",
      "description": "Admin API key for the Automation node"
    },
    "trustAllSSLCertificates": {
      "type": "boolean",
      "description": "Whether to trust all certificates"
    },
    "governCheckPolicy": {
      "type": "string",
      "description": "The Govern check policy to prevent (PREVENT), warn (WARN) or do nothing (NO_CHECK) when the bundle is not approved in Govern"
    }
  }
}

Get infra settings
GET/project-deployer/infras/{infraId}/settings

Retrieves the settings of an Automation infra.


πŸ”’ Required privileges : ADMIN on the infra

Example URI

GET /project-deployer/infras/infra-id/settings
URI Parameters
HideShow
infraId
string (required) Example: infra-id

the ID of the infra

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "infra-id",
  "permissions": [
    {
      "group": "data_scientists",
      "read": true,
      "deploy": true,
      "admin": false
    }
  ],
  "versionTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "autoconfigureFromNodesDirectory": false,
  "nodeId": "node-id",
  "automationNodeUrl": "http://automation:1111",
  "adminApiKey": "tl1cba6Dy3uZCVy0q1RgtDFcGvCO5Nfh",
  "trustAllSSLCertificates": true,
  "governCheckPolicy": "WARN"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the infra"
    },
    "permissions": {
      "type": "array",
      "description": "A list of permission dictionaries for user groups (permissions being read, deploy, admin)"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "autoconfigureFromNodesDirectory": {
      "type": "boolean"
    },
    "nodeId": {
      "type": "string",
      "description": "ID of the Automation node"
    },
    "automationNodeUrl": {
      "type": "string",
      "description": "URL of the Automation node"
    },
    "adminApiKey": {
      "type": "string",
      "description": "Admin API key for the Automation node"
    },
    "trustAllSSLCertificates": {
      "type": "boolean",
      "description": "Whether to trust all certificates"
    },
    "governCheckPolicy": {
      "type": "string",
      "description": "The Govern check policy to prevent (PREVENT), warn (WARN) or do nothing (NO_CHECK) when the bundle is not approved in Govern"
    }
  }
}

Save infra settings
PUT/project-deployer/infras/{infraId}/settings

Saves the settings of an Automation infra. You should first retrieve the current settings with a GET call.


πŸ”’ Required privileges : ADMIN on the infra

Example URI

PUT /project-deployer/infras/infra-id/settings
URI Parameters
HideShow
infraId
string (required) Example: infra-id

the ID of the infra

Request  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "infra-id",
  "permissions": [
    {
      "group": "data_scientists",
      "read": true,
      "deploy": true,
      "admin": false
    }
  ],
  "versionTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "creationTag": {
    "versionNumber": 6,
    "lastModifiedBy": {
      "login": "niceUser"
    },
    "lastModifiedOn": 1554386952201
  },
  "autoconfigureFromNodesDirectory": false,
  "nodeId": "node-id",
  "automationNodeUrl": "http://automation:1111",
  "adminApiKey": "tl1cba6Dy3uZCVy0q1RgtDFcGvCO5Nfh",
  "trustAllSSLCertificates": true,
  "governCheckPolicy": "WARN"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the infra"
    },
    "permissions": {
      "type": "array",
      "description": "A list of permission dictionaries for user groups (permissions being read, deploy, admin)"
    },
    "creationTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Creation version tag"
    },
    "versionTag": {
      "type": "object",
      "properties": {
        "versionNumber": {
          "type": "number"
        },
        "lastModifiedBy": {
          "type": "object",
          "properties": {
            "login": {
              "type": "string"
            },
            "displayName": {
              "type": "string"
            }
          }
        },
        "lastModifiedOn": {
          "type": "number"
        }
      },
      "description": "Current version tag"
    },
    "autoconfigureFromNodesDirectory": {
      "type": "boolean"
    },
    "nodeId": {
      "type": "string",
      "description": "ID of the Automation node"
    },
    "automationNodeUrl": {
      "type": "string",
      "description": "URL of the Automation node"
    },
    "adminApiKey": {
      "type": "string",
      "description": "Admin API key for the Automation node"
    },
    "trustAllSSLCertificates": {
      "type": "boolean",
      "description": "Whether to trust all certificates"
    },
    "governCheckPolicy": {
      "type": "string",
      "description": "The Govern check policy to prevent (PREVENT), warn (WARN) or do nothing (NO_CHECK) when the bundle is not approved in Govern"
    }
  }
}
Response  204

Delete infra
DELETE/project-deployer/infras/{infraId}

Deletes an Automation infra. Only infras not currently used by any deployments can be deleted.


πŸ”’ Required privileges : ADMIN on the infra

Example URI

DELETE /project-deployer/infras/infra-id
URI Parameters
HideShow
infraId
string (required) Example: infra-id

the ID of the infra

Response  204

Wiki

Wiki

Get wiki
GET/projects/{projectKey}/wiki/

Get wiki properties (taxonomy, home article)


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of the project

Response  200
HideShow

Returns a [Wiki] object.

Headers
Content-Type: application/json
Body
{
  "projectKey": "WIKITEST",
  "homeArticleId": "Homepage",
  "taxonomy": [
    {
      "id": "Page 1",
      "children": [
        {
          "id": "Page 2",
          "children": []
        }
      ]
    },
    {
      "id": "Homepage",
      "children": []
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of the wiki"
    },
    "homeArticleId": {
      "type": "string",
      "description": "The article ID that is used as homepage"
    },
    "taxonomy": {
      "type": "array",
      "description": "Taxonomy of the articles"
    }
  }
}

Update wiki
PUT/projects/{projectKey}/wiki/

Update the wiki properties (taxonomy, home article).


πŸ”’ Required privileges : WRITE_CONF

Example URI

PUT /projects/projectKey/wiki/
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "WIKITEST",
  "homeArticleId": "Page 1",
  "taxonomy": [
    {
      "id": "Page 1",
      "children": [
        {
          "id": "Page 2",
          "children": []
        }
      ]
    },
    {
      "id": "Homepage",
      "children": []
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of the wiki"
    },
    "homeArticleId": {
      "type": "string",
      "description": "The article ID that is used as homepage"
    },
    "taxonomy": {
      "type": "array",
      "description": "Taxonomy of the articles"
    }
  }
}
Response  200
HideShow

Returns the updated [Wiki] object.

Headers
Content-Type: application/json
Body
{
  "projectKey": "WIKITEST",
  "homeArticleId": "Page 1",
  "taxonomy": [
    {
      "id": "Page 1",
      "children": [
        {
          "id": "Page 2",
          "children": []
        }
      ]
    },
    {
      "id": "Homepage",
      "children": []
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Project key of the wiki"
    },
    "homeArticleId": {
      "type": "string",
      "description": "The article ID that is used as homepage"
    },
    "taxonomy": {
      "type": "array",
      "description": "Taxonomy of the articles"
    }
  }
}

Create article
POST/projects/{projectKey}/wiki/

Create an article (metadata).


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the key of the project

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "WIKITEST",
  "id": "New page",
  "parent": "Page 1"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}
Response  200
HideShow

Returns the corresponding [ArticleWithPayload] object.

Headers
Content-Type: application/json
Body
{
  "article": {
    "projectKey": "WIKITEST",
    "id": "New page",
    "layout": "WIKI_ARTICLE",
    "attachments": [],
    "tags": []
  },
  "payload": ""
}

Article

Get article
GET/projects/{projectKey}/wiki/{articleId}

Get an article (metadata, payload)


πŸ”’ Required privileges : READ_CONF

Example URI

GET /projects/projectKey/wiki/articleId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

articleId
string (required) 

the article ID

Response  200
HideShow

Returns a [ArticleWithPayload] object.

Headers
Content-Type: application/json
Body
{
  "article": {
    "projectKey": "WIKITEST",
    "id": "Page 1",
    "layout": "WIKI_ARTICLE",
    "attachments": [
      {
        "attachmentType": "DSS_OBJECT",
        "taggableType": "DATASET",
        "projectKey": "WIKITEST",
        "id": "dataset1"
      }
    ],
    "tags": [
      "tag1",
      "tag2"
    ]
  },
  "payload": "# Page 1 article\n\nContent"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "article": {
      "type": "object",
      "properties": {
        "projectKey": {
          "type": "string",
          "description": "Project key of this article"
        },
        "id": {
          "type": "string",
          "description": "Article id"
        },
        "layout": {
          "type": "string",
          "description": "Article layout (WIKI_ARTICLE or FOLDER)"
        },
        "attachments": {
          "type": "array",
          "description": "Attachments of the article"
        },
        "tags": {
          "type": "array",
          "description": "Tags of the article"
        }
      },
      "description": "Article metadata"
    },
    "payload": {
      "type": "string",
      "description": "Content of article"
    }
  }
}

Update article
PUT/projects/{projectKey}/wiki/{articleId}

Update article (metadata, payload)


πŸ”’ Required privileges : WRITE_CONF

Example URI

PUT /projects/projectKey/wiki/articleId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

articleId
string (required) 

the article ID

Request
HideShow

Note: payload uses markdown syntax.

Headers
Content-Type: application/json
Body
{
  "article": {
    "projectKey": "WIKITEST",
    "id": "Page 1",
    "layout": "FOLDER",
    "attachments": [
      {
        "attachmentType": "DSS_OBJECT",
        "taggableType": "DATASET",
        "projectKey": "WIKITEST",
        "id": "dataset1"
      }
    ],
    "tags": [
      "tag1",
      "tag2 (edited)"
    ]
  },
  "payload": "# Page 1 article\n\nContent (edited)"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "article": {
      "type": "object",
      "properties": {
        "projectKey": {
          "type": "string",
          "description": "Project key of this article"
        },
        "id": {
          "type": "string",
          "description": "Article id"
        },
        "layout": {
          "type": "string",
          "description": "Article layout (WIKI_ARTICLE or FOLDER)"
        },
        "attachments": {
          "type": "array",
          "description": "Attachments of the article"
        },
        "tags": {
          "type": "array",
          "description": "Tags of the article"
        }
      },
      "description": "Article metadata"
    },
    "payload": {
      "type": "string",
      "description": "Content of article"
    }
  }
}
Response  200
HideShow

Returns the corresponding [ArticleAndPayload] object.

Headers
Content-Type: application/json
Body
{
  "article": {
    "projectKey": "WIKITEST",
    "id": "Page 1",
    "layout": "FOLDER",
    "attachments": [
      {
        "attachmentType": "DSS_OBJECT",
        "taggableType": "DATASET",
        "projectKey": "WIKITEST",
        "id": "dataset1"
      }
    ],
    "tags": [
      "tag1",
      "tag2 (edited)"
    ]
  },
  "payload": "# Page 1 article\n\nContent (edited)"
}

Discussions

Discussions

Get discussions
GET/projects/{projectKey}/discussions/{objectType}/{objectId}/

Get discussions on an object


πŸ”’ Required privileges : READ_DASHBOARD

Example URI

GET /projects/projectKey/discussions/objectType/objectId/
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

objectType
string (required) 

the DSS object type

objectId
string (required) 

the DSS object ID

Response  200
HideShow

Returns an array of [Discussion] objects.

Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "DISCUTEST",
    "id": "L8gkpoI6",
    "objectType": "PROJECT",
    "objectId": "DISCUTEST",
    "objectDisplayName": "Discussion project",
    "topic": "Project infos",
    "lastReplyTime": 1517245249936,
    "users": {
      "user1": {
        "login": "user1",
        "lastReplyTime": 1517245249936,
        "lastReadTime": 1517245249936
      }
    },
    "closedOn": 0,
    "closedBy": ""
  },
  {
    "projectKey": "DISCUTEST",
    "id": "AZgd6ds0",
    "objectType": "PROJECT",
    "objectId": "DISCUTEST",
    "objectDisplayName": "Discussion project",
    "topic": "Project deletion",
    "lastReplyTime": 1517218351503,
    "users": {
      "user1": {
        "login": "user1",
        "lastReplyTime": 1517218351503,
        "lastReadTime": 1517218351503
      }
    },
    "closedOn": 1517218351503,
    "closedBy": "user1"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create discussion
POST/projects/{projectKey}/discussions/{objectType}/{objectId}/

Create a discussion on an object


πŸ”’ Required privileges : READ_DASHBOARD

Example URI

POST /projects/projectKey/discussions/objectType/objectId/
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

objectType
string (required) 

the DSS object type

objectId
string (required) 

the DSS object ID

Request
HideShow

Note: the reply uses markdown syntax.

Headers
Content-Type: application/json
Body
{
  "topic": "An interesting discussion",
  "reply": "Discussion content here"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}
Response  200
HideShow

Returns the newly created [Discussion].

Headers
Content-Type: application/json
Body
{
  "projectKey": "DISCUTEST",
  "id": "Ed6Fgi89",
  "objectType": "PROJECT",
  "objectId": "DISCUTEST",
  "objectDisplayName": "Discussion project",
  "topic": "An interesting discussion",
  "lastReplyTime": 1517322182967,
  "users": {
    "user1": {
      "login": "user1",
      "lastReplyTime": 1517322182967,
      "lastReadTime": 1517322182967
    }
  },
  "closedOn": 0,
  "closedBy": "",
  "replies": [
    {
      "id": "Ja8Stes4",
      "text": "Discussion content here",
      "author": "user1",
      "time": 1517322182967,
      "editedOn": 0
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Key of the project"
    },
    "id": {
      "type": "string",
      "description": "the discussion ID"
    },
    "objectType": {
      "type": "string",
      "description": "DSS object type"
    },
    "objectId": {
      "type": "string",
      "description": "DSS object ID"
    },
    "topic": {
      "type": "string",
      "description": "the discussion topic"
    },
    "lastReplyTime": {
      "type": "number",
      "description": "the timestamp of the last reply"
    },
    "users": {
      "type": "object",
      "properties": {},
      "description": "the map of participants"
    },
    "closedOn": {
      "type": "number",
      "description": "the timestamp when the discussion has been closed or 0"
    },
    "closedBy": {
      "type": "string",
      "description": "the login of the user that closed the discussion or empty"
    },
    "replies": {
      "type": "array"
    }
  }
}

Discussion

Get discussion
GET/projects/{projectKey}/discussions/{objectType}/{objectId}/{discussionId}

Get discussion


πŸ”’ Required privileges : READ_DASHBOARD

Example URI

GET /projects/projectKey/discussions/objectType/objectId/discussionId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

objectType
string (required) 

the DSS object type

objectId
string (required) 

the DSS object ID

discussionId
string (required) 

the discussion ID

Response  200
HideShow

Returns the discussion with its replies.

Headers
Content-Type: application/json
Body
{
  "projectKey": "DISCUTEST",
  "id": "L8gkpoI6",
  "objectType": "PROJECT",
  "objectId": "DISCUTEST",
  "objectDisplayName": "Discussion project",
  "topic": "Project infos",
  "lastReplyTime": 1517322182967,
  "users": {
    "user1": {
      "login": "user1",
      "lastReplyTime": 1517322182967,
      "lastReadTime": 1517322182967
    }
  },
  "closedOn": 0,
  "closedBy": "",
  "replies": [
    {
      "id": "Ja8Stes4",
      "text": "What is the topic?",
      "author": "user1",
      "time": 1517322182967,
      "editedOn": 0
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Key of the project"
    },
    "id": {
      "type": "string",
      "description": "the discussion ID"
    },
    "objectType": {
      "type": "string",
      "description": "DSS object type"
    },
    "objectId": {
      "type": "string",
      "description": "DSS object ID"
    },
    "topic": {
      "type": "string",
      "description": "the discussion topic"
    },
    "lastReplyTime": {
      "type": "number",
      "description": "the timestamp of the last reply"
    },
    "users": {
      "type": "object",
      "properties": {},
      "description": "the map of participants"
    },
    "closedOn": {
      "type": "number",
      "description": "the timestamp when the discussion has been closed or 0"
    },
    "closedBy": {
      "type": "string",
      "description": "the login of the user that closed the discussion or empty"
    },
    "replies": {
      "type": "array"
    }
  }
}

Update discussion
PUT/projects/{projectKey}/discussions/{objectType}/{objectId}/{discussionId}

Update discussion (change DSS object inside same project, edit topic)


πŸ”’ Required privileges : READ_DASHBOARD

Example URI

PUT /projects/projectKey/discussions/objectType/objectId/discussionId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

objectType
string (required) 

the DSS object type

objectId
string (required) 

the DSS object ID

discussionId
string (required) 

the discussion ID

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "projectKey": "DISCUTEST",
  "id": "L8gkpoI6",
  "objectType": "PROJECT",
  "objectId": "DISCUTEST",
  "topic": "Project infos (edited)",
  "lastReplyTime": 1517322182967,
  "closedOn": 1517322182967,
  "closedBy": "user1"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Key of the project"
    },
    "id": {
      "type": "string",
      "description": "the discussion ID"
    },
    "objectType": {
      "type": "string",
      "description": "DSS object type"
    },
    "objectId": {
      "type": "string",
      "description": "DSS object ID"
    },
    "topic": {
      "type": "string",
      "description": "the discussion topic"
    },
    "lastReplyTime": {
      "type": "number",
      "description": "the timestamp of the last reply"
    },
    "users": {
      "type": "object",
      "properties": {},
      "description": "the map of participants"
    },
    "closedOn": {
      "type": "number",
      "description": "the timestamp when the discussion has been closed or 0"
    },
    "closedBy": {
      "type": "string",
      "description": "the login of the user that closed the discussion or empty"
    },
    "replies": {
      "type": "array"
    }
  }
}
Response  200
HideShow

Returns the discussion with its replies.

Headers
Content-Type: application/json
Body
{
  "projectKey": "DISCUTEST",
  "id": "L8gkpoI6",
  "objectType": "PROJECT",
  "objectId": "DISCUTEST",
  "objectDisplayName": "Discussion project",
  "topic": "Project infos (edited)",
  "lastReplyTime": 1517322182967,
  "users": {
    "user1": {
      "login": "user1",
      "lastReplyTime": 1517322182967,
      "lastReadTime": 1517322182967
    }
  },
  "closedOn": 1517322182967,
  "closedBy": "user1",
  "replies": [
    {
      "id": "Ja8Stes4",
      "text": "What is the topic?",
      "author": "user1",
      "time": 1517322182967,
      "editedOn": 0
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Key of the project"
    },
    "id": {
      "type": "string",
      "description": "the discussion ID"
    },
    "objectType": {
      "type": "string",
      "description": "DSS object type"
    },
    "objectId": {
      "type": "string",
      "description": "DSS object ID"
    },
    "topic": {
      "type": "string",
      "description": "the discussion topic"
    },
    "lastReplyTime": {
      "type": "number",
      "description": "the timestamp of the last reply"
    },
    "users": {
      "type": "object",
      "properties": {},
      "description": "the map of participants"
    },
    "closedOn": {
      "type": "number",
      "description": "the timestamp when the discussion has been closed or 0"
    },
    "closedBy": {
      "type": "string",
      "description": "the login of the user that closed the discussion or empty"
    },
    "replies": {
      "type": "array"
    }
  }
}

Discussion replies

Reply
POST/projects/{projectKey}/discussions/{objectType}/{objectId}/{discussionId}/replies/

Reply to a discussion


πŸ”’ Required privileges : READ_DASHBOARD

Example URI

POST /projects/projectKey/discussions/objectType/objectId/discussionId/replies/
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

objectType
string (required) 

the DSS object type

objectId
string (required) 

the DSS object ID

discussionId
string (required) 

the discussion ID

Request
HideShow

Note: the reply uses markdown syntax.

Headers
Content-Type: application/json
Body
{
  "reply": "A new reply"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}
Response  200
HideShow

Returns the discussion with its replies.

Headers
Content-Type: application/json
Body
{
  "projectKey": "DISCUTEST",
  "id": "L8gkpoI6",
  "objectType": "PROJECT",
  "objectId": "DISCUTEST",
  "objectDisplayName": "Discussion project",
  "topic": "Project infos",
  "lastReplyTime": 1517322234567,
  "users": {
    "user1": {
      "login": "user1",
      "lastReplyTime": 1517322234567,
      "lastReadTime": 1517322182967
    }
  },
  "closedOn": 0,
  "closedBy": "",
  "replies": [
    {
      "id": "Ja8Stes4",
      "text": "What is the topic?",
      "author": "user1",
      "time": 1517322182967,
      "editedOn": 0
    },
    {
      "id": "v43SD98c",
      "text": "A new reply",
      "author": "user1",
      "time": 1517322234567,
      "editedOn": 0
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "projectKey": {
      "type": "string",
      "description": "Key of the project"
    },
    "id": {
      "type": "string",
      "description": "the discussion ID"
    },
    "objectType": {
      "type": "string",
      "description": "DSS object type"
    },
    "objectId": {
      "type": "string",
      "description": "DSS object ID"
    },
    "topic": {
      "type": "string",
      "description": "the discussion topic"
    },
    "lastReplyTime": {
      "type": "number",
      "description": "the timestamp of the last reply"
    },
    "users": {
      "type": "object",
      "properties": {},
      "description": "the map of participants"
    },
    "closedOn": {
      "type": "number",
      "description": "the timestamp when the discussion has been closed or 0"
    },
    "closedBy": {
      "type": "string",
      "description": "the login of the user that closed the discussion or empty"
    },
    "replies": {
      "type": "array"
    }
  }
}

Dashboards

Dashboards

List Dashboards
GET/projects/{projectKey}/dashboards/

List the dashboards.


πŸ”’ Required privileges : READ_DASHBOARDS

Example URI

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

the key of the project

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "projectKey": "Hello, world!",
    "id": "Hello, world!",
    "name": "Hello, world!",
    "tags": [
      "Hello, world!"
    ],
    "shortDesc": "Hello, world!",
    "lastModifiedBy": {
      "login": "Hello, world!",
      "displayName": "Hello, world!"
    },
    "lastModifiedOn": 1,
    "createdBy": {
      "login": "Hello, world!",
      "displayName": "Hello, world!",
      "email": "Hello, world!"
    },
    "createdOn": 1,
    "owner": "Hello, world!",
    "ownerDisplayName": "Hello, world!",
    "listed": true,
    "numPages": 1,
    "numTiles": 1
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create Dashboard
POST/projects/{projectKey}/dashboards/

Create a new dashboard.

Important : most attributes of dashboards may be modified in future releases. It is recommended that you use the GET Dashboard call to retrieve an existing dashboard and modify it to suit your needs and create a new dashboard.


πŸ”’ Required privileges : WRITE_DASHBOARDS

Example URI

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

the key of the project

Request  Create Dashboard
HideShow
Headers
Content-Type: application/json
Body
{
  "owner": "",
  "listed": false,
  "name": "",
  "pages": [
    {
      "id": "",
      "grid": {
        "tiles": [
          {
            "tileType": "INSIGHT",
            "box": {
              "top": 0,
              "left": 0,
              "width": 0,
              "height": 0
            },
            "clickAction": "DO_NOTHING",
            "targetInsightId": "",
            "tileParams": {},
            "title": "",
            "showTitle": "YES",
            "insightId": "",
            "insightType": "",
            "displayMode": "INSIGHT",
            "imageId": "",
            "resizeImageMode": "ORIG_SIZE"
          }
        ]
      },
      "title": "",
      "showTitle": false,
      "backgroundColor": ""
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Login of the creator of the dashboard"
    },
    "listed": {
      "type": "boolean",
      "description": "Boolean indicating if the dashboard is private or public (i.e. promoted)"
    },
    "name": {
      "type": "string",
      "description": "Name of the dashboard"
    },
    "pages": {
      "type": "array",
      "description": "Pages to display on the dashboard"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "owner": "",
  "listed": false,
  "name": "",
  "pages": [
    {
      "id": "",
      "grid": {
        "tiles": [
          {
            "tileType": "INSIGHT",
            "box": {
              "top": 0,
              "left": 0,
              "width": 0,
              "height": 0
            },
            "clickAction": "DO_NOTHING",
            "targetInsightId": "",
            "tileParams": {},
            "title": "",
            "showTitle": "YES",
            "insightId": "",
            "insightType": "",
            "displayMode": "INSIGHT",
            "imageId": "",
            "resizeImageMode": "ORIG_SIZE"
          }
        ]
      },
      "title": "",
      "showTitle": false,
      "backgroundColor": ""
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Login of the creator of the dashboard"
    },
    "listed": {
      "type": "boolean",
      "description": "Boolean indicating if the dashboard is private or public (i.e. promoted)"
    },
    "name": {
      "type": "string",
      "description": "Name of the dashboard"
    },
    "pages": {
      "type": "array",
      "description": "Pages to display on the dashboard"
    }
  }
}

Dashboard

Get Dashboard
GET/projects/{projectKey}/dashboards/{dashboardId}

Retrieve a dashboard object describing it

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 : READ_DASHBOARDS

Example URI

GET /projects/projectKey/dashboards/dashboardId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

dashboardId
string (required) 

the id of the dashboard

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "owner": "",
  "listed": false,
  "name": "",
  "pages": [
    {
      "id": "",
      "grid": {
        "tiles": [
          {
            "tileType": "INSIGHT",
            "box": {
              "top": 0,
              "left": 0,
              "width": 0,
              "height": 0
            },
            "clickAction": "DO_NOTHING",
            "targetInsightId": "",
            "tileParams": {},
            "title": "",
            "showTitle": "YES",
            "insightId": "",
            "insightType": "",
            "displayMode": "INSIGHT",
            "imageId": "",
            "resizeImageMode": "ORIG_SIZE"
          }
        ]
      },
      "title": "",
      "showTitle": false,
      "backgroundColor": ""
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Login of the creator of the dashboard"
    },
    "listed": {
      "type": "boolean",
      "description": "Boolean indicating if the dashboard is private or public (i.e. promoted)"
    },
    "name": {
      "type": "string",
      "description": "Name of the dashboard"
    },
    "pages": {
      "type": "array",
      "description": "Pages to display on the dashboard"
    }
  }
}

Update the Dashboard
PUT/projects/{projectKey}/dashboards/{dashboardId}

Update the dashboard.

The dashboard object given as parameter in of a PUT call MUST have been previously obtained from a GET dashboard 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_DASHBOARDS

Example URI

PUT /projects/projectKey/dashboards/dashboardId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

dashboardId
string (required) 

the id of the dashboard

Request  Update Dashboard
HideShow
Headers
Content-Type: application/json
Body
{
  "owner": "",
  "listed": false,
  "name": "",
  "pages": [
    {
      "id": "",
      "grid": {
        "tiles": [
          {
            "tileType": "INSIGHT",
            "box": {
              "top": 0,
              "left": 0,
              "width": 0,
              "height": 0
            },
            "clickAction": "DO_NOTHING",
            "targetInsightId": "",
            "tileParams": {},
            "title": "",
            "showTitle": "YES",
            "insightId": "",
            "insightType": "",
            "displayMode": "INSIGHT",
            "imageId": "",
            "resizeImageMode": "ORIG_SIZE"
          }
        ]
      },
      "title": "",
      "showTitle": false,
      "backgroundColor": ""
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Login of the creator of the dashboard"
    },
    "listed": {
      "type": "boolean",
      "description": "Boolean indicating if the dashboard is private or public (i.e. promoted)"
    },
    "name": {
      "type": "string",
      "description": "Name of the dashboard"
    },
    "pages": {
      "type": "array",
      "description": "Pages to display on the dashboard"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "owner": "",
  "listed": false,
  "name": "",
  "pages": [
    {
      "id": "",
      "grid": {
        "tiles": [
          {
            "tileType": "INSIGHT",
            "box": {
              "top": 0,
              "left": 0,
              "width": 0,
              "height": 0
            },
            "clickAction": "DO_NOTHING",
            "targetInsightId": "",
            "tileParams": {},
            "title": "",
            "showTitle": "YES",
            "insightId": "",
            "insightType": "",
            "displayMode": "INSIGHT",
            "imageId": "",
            "resizeImageMode": "ORIG_SIZE"
          }
        ]
      },
      "title": "",
      "showTitle": false,
      "backgroundColor": ""
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Login of the creator of the dashboard"
    },
    "listed": {
      "type": "boolean",
      "description": "Boolean indicating if the dashboard is private or public (i.e. promoted)"
    },
    "name": {
      "type": "string",
      "description": "Name of the dashboard"
    },
    "pages": {
      "type": "array",
      "description": "Pages to display on the dashboard"
    }
  }
}

Delete the Dashboard
DELETE/projects/{projectKey}/dashboards/{dashboardId}

Delete a dashboard.


πŸ”’ Required privileges : WRITE_DASHBOARDS

Example URI

DELETE /projects/projectKey/dashboards/dashboardId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

dashboardId
string (required) 

the id of the dashboard

Response  204

Export the dashboard
POST/projects/{projectKey}/dashboards/{dashboardId}/action/export

In order to use this API method, you need to have setup the graphics export feature on your DSS instance.

Create a dashboard export and returns it in the response. Then, the dashboard export will be deleted on the server side.


πŸ”’ Required privileges : READ_DASHBOARDS

Example URI

POST /projects/projectKey/dashboards/dashboardId/action/export
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

dashboardId
string (required) 

the id of the dashboard

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "paperSize": "A4",
    "orientation": "PORTRAIT",
    "fileType": "PDF",
    "slideIndex": 0,
    "filtersBySlide": ["slide1Filters", "slide2Filters", ...]
}
Response  200

Insights

Insights

List Insights
GET/projects/{projectKey}/insights/

List the insights.


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of the project

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

Create Insight
POST/projects/{projectKey}/insights/

Create a new insight.

Important : most attributes of insights may be modified in future releases. It is recommended that you use the GET Insight call to retrieve an existing insight and modify it to suit your needs and create a new insight.


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the key of the project

Request  Create Insight
HideShow
Headers
Content-Type: application/json
Body
{
  "insightPrototype": {
    "id": "",
    "projectKey": 0,
    "type": 0,
    "name": "",
    "listed": false,
    "owner": "",
    "params": {}
  },
  "contentType": "",
  "payload": ""
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "insightPrototype": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID of the insight"
        },
        "projectKey": {
          "type": "number",
          "description": "Project key on which the insight belongs"
        },
        "type": {
          "type": "number",
          "description": "Type of the insight"
        },
        "name": {
          "type": "string",
          "description": "Name of the insight"
        },
        "listed": {
          "type": "boolean",
          "description": "Boolean indicating if the insight is private or public (i.e. promoted)"
        },
        "owner": {
          "type": "string",
          "description": "Owner login of the insight"
        },
        "params": {
          "type": "object",
          "properties": {},
          "description": "Configuration of the insight"
        }
      },
      "description": "Insight that will be created"
    },
    "contentType": {
      "type": "string",
      "description": "Used to specify content type of the file (Only useful when the insightPrototype.type is `static_file`)"
    },
    "payload": {
      "type": "string",
      "description": "Optional payload used to create the insight"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the object"
    }
  }
}

Insight

Get Insight
GET/projects/{projectKey}/insights/{insightId}

Retrieve an insight object describing it

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 : READ_CONF

Example URI

GET /projects/projectKey/insights/insightId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

insightId
string (required) 

the id of the insight

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "",
  "projectKey": 0,
  "type": 0,
  "name": "",
  "listed": false,
  "owner": "",
  "params": {}
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the insight"
    },
    "projectKey": {
      "type": "number",
      "description": "Project key on which the insight belongs"
    },
    "type": {
      "type": "number",
      "description": "Type of the insight"
    },
    "name": {
      "type": "string",
      "description": "Name of the insight"
    },
    "listed": {
      "type": "boolean",
      "description": "Boolean indicating if the insight is private or public (i.e. promoted)"
    },
    "owner": {
      "type": "string",
      "description": "Owner login of the insight"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Configuration of the insight"
    }
  }
}

Update the Insight
POST/projects/{projectKey}/insights/{insightId}

Update an insight.

The insight object given as parameter in of a POST call MUST have been previously obtained from a GET insight 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

POST /projects/projectKey/insights/insightId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

insightId
string (required) 

the id of the insight

Request  Update Insight
HideShow
Headers
Content-Type: application/json
Body
{
  "insight": {
    "id": "",
    "projectKey": 0,
    "type": 0,
    "name": "",
    "listed": false,
    "owner": "",
    "params": {}
  },
  "contentType": "",
  "payload": ""
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "insight": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID of the insight"
        },
        "projectKey": {
          "type": "number",
          "description": "Project key on which the insight belongs"
        },
        "type": {
          "type": "number",
          "description": "Type of the insight"
        },
        "name": {
          "type": "string",
          "description": "Name of the insight"
        },
        "listed": {
          "type": "boolean",
          "description": "Boolean indicating if the insight is private or public (i.e. promoted)"
        },
        "owner": {
          "type": "string",
          "description": "Owner login of the insight"
        },
        "params": {
          "type": "object",
          "properties": {},
          "description": "Configuration of the insight"
        }
      },
      "description": "Insight that will be updated"
    },
    "contentType": {
      "type": "string",
      "description": "Used to specify content type of the file (Only useful when the insightPrototype.type is `static_file`)"
    },
    "payload": {
      "type": "string",
      "description": "Optional payload used to update the insight"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "",
  "projectKey": 0,
  "type": 0,
  "name": "",
  "listed": false,
  "owner": "",
  "params": {}
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the insight"
    },
    "projectKey": {
      "type": "number",
      "description": "Project key on which the insight belongs"
    },
    "type": {
      "type": "number",
      "description": "Type of the insight"
    },
    "name": {
      "type": "string",
      "description": "Name of the insight"
    },
    "listed": {
      "type": "boolean",
      "description": "Boolean indicating if the insight is private or public (i.e. promoted)"
    },
    "owner": {
      "type": "string",
      "description": "Owner login of the insight"
    },
    "params": {
      "type": "object",
      "properties": {},
      "description": "Configuration of the insight"
    }
  }
}

Delete the Insight
DELETE/projects/{projectKey}/insights/{insightId}

Delete an insight.


πŸ”’ Required privileges : WRITE_CONF

Example URI

DELETE /projects/projectKey/insights/insightId
URI Parameters
HideShow
projectKey
string (required) 

the key of the project

insightId
string (required) 

the id of the insight

Response  200

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/connections/{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/connections/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/connections/{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/connections/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/connections/{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/connections/connectionName
URI Parameters
HideShow
connectionName
string (required) 

the name of a connection in DSS

Response  204

Connections names

List connections names
GET/connections/get-names/{?type}

List all the connections names available on the DSS instance.

Unlike /admin/connections, you don’t need Admin privileges to call this route.

Example URI

GET /connections/get-names/?type=
URI Parameters
HideShow
type
string (required) 

Returns only connections with this type. Use all if you don’t want to filter.

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  "filesystem_managed",
  "filesystem_folders",
  "filesystem_root"
]

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 : 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.


πŸ”’ Required privileges : Admin

Example URI

POST /admin/users
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "login": "UserA",
  "sourceType": "LOCAL",
  "displayName": "User A",
  "email": "",
  "groups": [],
  "userProfile": "DATA_ANALYST",
  "password": "password"
}
Response  201
HideShow
Body
{
  "msg": "Created user UserA"
}

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  200
HideShow
Body
{
  "msg": "Edited user UserA"
}

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  200
HideShow
Body
{
  "msg": "Deleted user UserA"
}

Resync a user
POST/admin/users/{login}/actions/resync

Resync the user

Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated flow documentation.


πŸ”’ Required privileges : Admin

Example URI

POST /admin/users/login/actions/resync
URI Parameters
HideShow
login
string (required) 

the login of a DSS user

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "messages": [],
    "anyMessage": false,
    "success": false,
    "warning": false,
    "error": false,
    "fatal": false
  }
}

Resync multiple users
POST/admin/users/actions/resync-multi

Resyncs multiple users

Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated flow documentation.


πŸ”’ Required privileges : Admin

Example URI

POST /admin/users/actions/resync-multi
Request
HideShow
Headers
Content-Type: application/json
Body
[
  "user1",
  "user2",
  "user3"
]
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "messages": [],
    "anyMessage": false,
    "success": false,
    "warning": false,
    "error": false,
    "fatal": false
  }
}

Fetch external users
GET/admin/users/actions/external-users

Fetches external users

Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated flow documentation.


πŸ”’ Required privileges : Admin

Example URI

GET /admin/users/actions/external-users
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw",
  "result": [
    {
      "status": "UNSYNCED",
      "userAttributes": {
        "login": "alice",
        "displayName": "Alice",
        "email": "[email protected]",
        "sourceGroupNames": [
          "externalGroupA"
        ],
        "dkuGroupNames": [
          "dssGroupA"
        ]
      },
      "profile": "READER"
    },
    {
      "status": "NOT_PROVISIONED",
      "userAttributes": {
        "login": "bob",
        "displayName": "Bob",
        "email": "[email protected]",
        "sourceGroupNames": [
          "externalGroupA"
        ],
        "dkuGroupNames": [
          "dssGroupA"
        ]
      },
      "profile": "READER"
    },
    {
      "status": "SYNCED",
      "userAttributes": {
        "login": "charlie",
        "displayName": "Charlie",
        "email": "[email protected]",
        "sourceGroupNames": [
          "externalGroupA"
        ],
        "dkuGroupNames": [
          "dssGroupA"
        ]
      },
      "profile": "READER"
    }
  ]
}

Fetch external groups
GET/admin/users/actions/external-groups

Fetches external groups

Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated flow documentation.


πŸ”’ Required privileges : Admin

Example URI

GET /admin/users/actions/external-groups
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 1561456214289,
  "runningTime": 0,
  "unknown": false,
  "jobId": "26S2LeJw",
  "result": [
    "externalGroupA",
    "externalGroupB",
    "externalGroupC"
  ]
}

Provision users
POST/admin/users/actions/provision

Provisions users

Returns a reference to a future, defined by its jobId. If the future has no result yet, polling on the jobId with GET task until the result is ready is needed to get the id of the generated flow documentation.


πŸ”’ Required privileges : Admin

Example URI

POST /admin/users/actions/provision
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "userSourceType": "AZURE_AD",
  "users": [
    {
      "login": "bob",
      "displayName": "Bob",
      "email": "[email protected]",
      "sourceGroupNames": [
        "externalGroupA"
      ],
      "dkuGroupNames": [
        "dssGroupA"
      ]
    },
    {
      "login": "charlie",
      "displayName": "Charlie",
      "email": "[email protected]",
      "sourceGroupNames": [
        "externalGroupA"
      ],
      "dkuGroupNames": [
        "dssGroupA"
      ]
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "hasResult": true,
  "aborted": false,
  "alive": false,
  "startTime": 0,
  "runningTime": 0,
  "unknown": false,
  "result": {
    "messages": [
      {
        "severity": "INFO",
        "isFatal": false,
        "code": "INFO_SECURITY_SUPPLIER_PROVISIONING_SUMMARY",
        "title": "User provisioning success",
        "details": "Imported 2/2 new users of source type 'AZURE_AD'",
        "message": "User provisioning success: Imported 2/2 new users of source type 'AZURE_AD'"
      }
    ],
    "maxSeverity": "INFO",
    "anyMessage": true,
    "success": false,
    "warning": false,
    "error": false,
    "fatal": false
  }
}

User last activity

Get all users last activity
GET/admin/users-activity

Get the last activity timestamps for all existing users


πŸ”’ Required privileges : Admin

Example URI

GET /admin/users-activity
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "login": "user1",
    "lastSuccessfulLogin": 1647448027194,
    "lastFailedLogin": 1647411934284,
    "lastLoaded": 1647448367338
  }
]

Get user last activity
GET/admin/users/{login}/activity

Get the user’s last activity timestamps


πŸ”’ Required privileges : Admin

Example URI

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

the login of a DSS user

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "login": "user1",
  "lastSuccessfulLogin": 1647448027194,
  "lastFailedLogin": 1647411934284,
  "lastLoaded": 1647448367338
}

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

Creates a group


πŸ”’ 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
HideShow
Headers
Content-Type: application/json
Body
{
  "msg": "Created group GroupB"
}

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  200
HideShow
Body
{
  "msg": "Edited group GroupB"
}

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  200
HideShow
Body
{
  "msg": "Deleted group GroupB"
}

Code envs

List code envs
GET/admin/code-envs

Retrieves the list of DSS code environments as a list


πŸ”’ Required privileges : Admin

Example URI

GET /admin/code-envs
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "kernelSpecName": "py-dku-venv-basic_external",
    "envLang": "PYTHON",
    "envName": "basic_external",
    "canUpdateCodeEnv": false,
    "owner": "admin",
    "isUptodate": false,
    "unknownKernelSpecStatus": false,
    "deploymentMode": "EXTERNAL_CONDA_NAMED"
  }
]

Code env

Create code env
POST/admin/code-envs/{envLang}/{envName}

Add a code environment to DSS


πŸ”’ Required privileges : Admin

Example URI

POST /admin/code-envs/envLang/envName
URI Parameters
HideShow
envLang
string (required) 

the type of code environment (python or r)

envName
string (required) 

the name of the code environment

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "deploymentMode" : "DESIGN_MANAGED",
    "pythonInterpreter" : PYTHON27,
    "installCorePackages" : true,
    "installJupyterSupport" : true
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "envName": "testapi3",
  "messages": {
    "anyMessage": false,
    "warning": false,
    "messages": [],
    "success": false,
    "error": false
  }
}

Get code env
GET/admin/code-envs/{envLang}/{envName}

Retrieves a Code env object describing a DSS code environment.

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/code-envs/envLang/envName
URI Parameters
HideShow
envLang
string (required) 

the type of code environment (python or r)

envName
string (required) 

the name of the code environment

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "deploymentMode": "DESIGN_MANAGED",
  "envName": "basic_managed",
  "kernelSpecName": "py-dku-venv-basic_managed",
  "owner": "admin",
  "permissions": [],
  "usableByAll": true,
  "specPackageList": "",
  "specCondaEnvironment": "",
  "actualCondaEnvironment": "",
  "mandatoryCondaEnvironment": "",
  "actualPackageList": "arrow==0.10.0\nbackports-abc==0.5\nbackports.shutil-get-terminal-size==1.0.0\ncertifi==2017.7.27.1\ndateparser==0.6.0\ndecorator==4.0.11\nenum34==1.1.6\nipykernel==4.6.1\nipython==5.4.1\nipython-genutils==0.1.0\njupyter-client==4.4.0\njupyter-core==4.2.1\nmoment==0.8.2\nnumpy==1.13.1\npandas==0.20.3\npathlib2==2.3.0\npexpect==4.2.1\npickleshare==0.7.4\nprompt-toolkit==1.0.15\nptyprocess==0.5.1\nPygments==2.2.0\npython-dateutil==2.5.3\npytz==2016.10\npyzmq==16.0.2\nregex==2017.7.28\nrequests==2.12.5\nruamel.ordereddict==0.4.13\nruamel.yaml==0.15.33\nscandir==1.5\nsimplegeneric==0.8.1\nsingledispatch==3.4.0.3\nsix==1.10.0\ntabulate==0.7.7\nterminado==0.6\ntimes==0.7\ntornado==4.4.2\ntraitlets==4.3.1\ntzlocal==1.4\nwcwidth==0.1.7\n",
  "mandatoryPackageList": "\npandas==0.20.3\nrequests==2.12.5\npython-dateutil==2.5.3\npytz==2016.10\n\ndecorator==4.0.11\npyzmq>=16.0\nipykernel==4.6.1\nipython_genutils==0.1.0\njupyter_client==4.4.0\njupyter_core==4.2.1\npexpect==4.2.1\npickleshare==0.7.4\nptyprocess==0.5.1\nsimplegeneric==0.8.1\ntraitlets==4.3.1\nterminado==0.6\ntornado==4.4.2",
  "desc": {
    "usableByAll": true,
    "owner": "admin",
    "permissions": [],
    "deploymentMode": "DESIGN_MANAGED",
    "installCorePackages": true,
    "installJupyterSupport": true,
    "conda": false,
    "pythonInterpreter": "PYTHON27",
    "yarnPythonBin": "some/python/on/yarn",
    "basePackagesInstallMethod": "PRE_BUILT"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "deploymentMode": {
      "type": "string"
    },
    "envLang": {
      "type": "string"
    },
    "envName": {
      "type": "string"
    },
    "owner": {
      "type": "string"
    },
    "usableByAll": {
      "type": "boolean"
    },
    "permissions": {
      "type": "array"
    }
  }
}

Update code env
PUT/admin/code-envs/{envLang}/{envName}

The Code env object given as parameter in of a PUT call MUST have been previously obtained from a [GET code-env] 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/code-envs/envLang/envName
URI Parameters
HideShow
envLang
string (required) 

the type of code environment (python or r)

envName
string (required) 

the name of the code environment

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "deploymentMode": "DESIGN_MANAGED",
  "envName": "basic_managed",
  "kernelSpecName": "py-dku-venv-basic_managed",
  "owner": "admin",
  "permissions": [],
  "usableByAll": true,
  "specPackageList": "",
  "specCondaEnvironment": "",
  "actualCondaEnvironment": "",
  "mandatoryCondaEnvironment": "",
  "actualPackageList": "arrow==0.10.0\nbackports-abc==0.5\nbackports.shutil-get-terminal-size==1.0.0\ncertifi==2017.7.27.1\ndateparser==0.6.0\ndecorator==4.0.11\nenum34==1.1.6\nipykernel==4.6.1\nipython==5.4.1\nipython-genutils==0.1.0\njupyter-client==4.4.0\njupyter-core==4.2.1\nmoment==0.8.2\nnumpy==1.13.1\npandas==0.20.3\npathlib2==2.3.0\npexpect==4.2.1\npickleshare==0.7.4\nprompt-toolkit==1.0.15\nptyprocess==0.5.1\nPygments==2.2.0\npython-dateutil==2.5.3\npytz==2016.10\npyzmq==16.0.2\nregex==2017.7.28\nrequests==2.12.5\nruamel.ordereddict==0.4.13\nruamel.yaml==0.15.33\nscandir==1.5\nsimplegeneric==0.8.1\nsingledispatch==3.4.0.3\nsix==1.10.0\ntabulate==0.7.7\nterminado==0.6\ntimes==0.7\ntornado==4.4.2\ntraitlets==4.3.1\ntzlocal==1.4\nwcwidth==0.1.7\n",
  "mandatoryPackageList": "\npandas==0.20.3\nrequests==2.12.5\npython-dateutil==2.5.3\npytz==2016.10\n\ndecorator==4.0.11\npyzmq>=16.0\nipykernel==4.6.1\nipython_genutils==0.1.0\njupyter_client==4.4.0\njupyter_core==4.2.1\npexpect==4.2.1\npickleshare==0.7.4\nptyprocess==0.5.1\nsimplegeneric==0.8.1\ntraitlets==4.3.1\nterminado==0.6\ntornado==4.4.2",
  "desc": {
    "usableByAll": true,
    "owner": "admin",
    "permissions": [],
    "deploymentMode": "DESIGN_MANAGED",
    "installCorePackages": true,
    "installJupyterSupport": true,
    "conda": false,
    "pythonInterpreter": "PYTHON27",
    "yarnPythonBin": "some/python/on/yarn",
    "basePackagesInstallMethod": "PRE_BUILT"
  }
}
Response  204

Delete code-env
DELETE/admin/code-envs/{envLang}/{envName}

Deletes a DSS code environement


πŸ”’ Required privileges : Admin

Example URI

DELETE /admin/code-envs/envLang/envName
URI Parameters
HideShow
envLang
string (required) 

the type of code environment (python or r)

envName
string (required) 

the name of the code environment

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": {
    "anyMessage": false,
    "error": false,
    "messages": [],
    "success": false,
    "warning": false
  }
}

Update code-env packages
POST/admin/code-envs/packages{?forceRebuildEnv}

Update the packages in a DSS code environement


πŸ”’ Required privileges : Admin

Example URI

POST /admin/code-envs/packages?forceRebuildEnv=
URI Parameters
HideShow
forceRebuildEnv
boolean (optional) 

If set to true, force a rebuild of the code environment

  • Default false
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": {
    "anyMessage": false,
    "error": false,
    "messages": [],
    "success": false,
    "warning": false
  }
}

Update jupyter integration
POST/admin/code-envs/jupyter{?active}

Update the integration to jupyter of a DSS code environement.


πŸ”’ Required privileges : Admin

Example URI

POST /admin/code-envs/jupyter?active=
URI Parameters
HideShow
active
string (required) 

whether to activate or deactivate the in+ Response 204

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": {
    "anyMessage": false,
    "error": false,
    "messages": [],
    "success": false,
    "warning": false
  }
}

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

Global tag categories

List categories
GET/admin/global-tag-categories

List all the global tag categories available on the DSS instance.

This call retrieves a dictionary of GlobalTagCategory objects as defined in GET global tag category.


πŸ”’ Required privileges : Admin

Example URI

GET /admin/global-tag-categories
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "name": "department",
    "globalTags": [
      {
        "name": "engineering",
        "color": "#0f6d82"
      },
      {
        "name": "marketing",
        "color": "#30b2d1"
      },
      {
        "name": "sales",
        "color": "#123883"
      }
    ],
    "appliesTo": [
      "PROJECT",
      "RECIPE",
      "SCENARIO"
    ]
  }
]

Create category
POST/admin/global-tag-categories

This call creates a new global tag category on the DSS instance.

Random colors are assigned to tags without specified colors.

If appliesTo field is not provided, the created category is applied to all available types.

appliesTo valid values are: PROJECT, DATASET, RECIPE, MANAGED_FOLDER, FLOW_ZONE, SAVED_MODEL, ANALYSIS, SQL_NOTEBOOK, JUPYTER_NOTEBOOK, ARTICLE, LAMBDA_SERVICE, SCENARIO, DASHBOARD, INSIGHT, WEB_APP, REPORT, STREAMING_ENDPOINT, STATISTICS_WORKSHEET and DATA_COLLECTION.


πŸ”’ Required privileges : Admin

Example URI

POST /admin/global-tag-categories
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "department",
  "globalTags": [
    {
      "name": "engineering"
    },
    {
      "name": "marketing"
    },
    {
      "name": "sales",
      "color": "#123883"
    }
  ],
  "appliesTo": [
    "PROJECT",
    "RECIPE",
    "SCENARIO"
  ]
}
Response  200
HideShow
Body
{
  "name": "department",
  "globalTags": [
    {
      "name": "engineering",
      "color": "#0f6d82"
    },
    {
      "name": "marketing",
      "color": "#30b2d1"
    },
    {
      "name": "sales",
      "color": "#123883"
    }
  ],
  "appliesTo": [
    "PROJECT",
    "RECIPE",
    "SCENARIO"
  ]
}

Global tag category

Get category
GET/admin/global-tag-categories/{categoryName}

Gets the details of a global tag category


πŸ”’ Required privileges : Admin

Example URI

GET /admin/global-tag-categories/categoryName
URI Parameters
HideShow
categoryName
string (required) 

the name of a global tag category in DSS

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "department",
  "globalTags": [
    {
      "name": "engineering",
      "color": "#0f6d82"
    },
    {
      "name": "marketing",
      "color": "#30b2d1"
    },
    {
      "name": "sales",
      "color": "#123883"
    }
  ],
  "appliesTo": [
    "PROJECT",
    "RECIPE",
    "SCENARIO"
  ]
}

Update category
PUT/admin/global-tag-categories/{categoryName}

Update one or more properties of a global tag category.

You can rename a category by supplying a name field in the body with a value different from the one in the parameters.

If globalTags field is omitted, the tags are not updated. Otherwise, the supplied tags overwrite the existing tags.

If appliesTo field is omitted, the value of appliesTo is not updated. Otherwise, it is overwritten with the provided values.


πŸ”’ Required privileges : Admin

Example URI

PUT /admin/global-tag-categories/categoryName
URI Parameters
HideShow
categoryName
string (required) 

the name of a global tag category in DSS

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "business-unit",
  "appliesTo": [
    "PROJECT",
    "SQL_NOTEBOOK"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json

Delete category
DELETE/admin/global-tag-categories/{?deletionMode}{?reassignTo}

Delete an existing global tag category.


πŸ”’ Required privileges : Admin

Example URI

DELETE /admin/global-tag-categories/?deletionMode=?reassignTo=
URI Parameters
HideShow
deletionMode
string (optional) Default: KEEP 

Specify how tagged objects are updated:

  • KEEP keeps the tags on tagged objects. They will just not appear as global tags anymore.

  • REMOVE removes the tags from tagged objects.

  • REASSIGN moves all tags to another category and update the tagged objects accordingly.

reassignTo
string (optional) 

When deletionMode=REASSIGN, name of the other category to merge with the deleted one.

Response  200
HideShow
Headers
Content-Type: application/json

Global tags

Create tag
POST/admin/global-tag-categories/{categoryName}/tags

Add a new tag to a global tag category.

If the color field is omitted, a random color is assigned to the created tag.


πŸ”’ Required privileges : Admin

Example URI

POST /admin/global-tag-categories/categoryName/tags
URI Parameters
HideShow
categoryName
string (required) 

the name of a global tag category in DSS

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "engineering",
  "color": "#0f6d82"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "engineering",
  "color": "#0f6d82"
}

Global tag

Get tag
GET/admin/global-tag-categories/{categoryName}/tags/{tagName}

Gets the details of a global tag from a category


πŸ”’ Required privileges : Admin

Example URI

GET /admin/global-tag-categories/categoryName/tags/tagName
URI Parameters
HideShow
categoryName
string (required) 

the name of a global tag category in DSS

tagName
string (required) 

the name of a tag of the category

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "engineering",
  "color": "#0f6d82"
}

Update tag
PUT/admin/global-tag-categories/{categoryName}/tags/{tagName}

Update one or more properties of a global tag.

You can rename a tag by supplying a β€œname” field in the body with a value different from the one in the parameters.

If color field is omitted, the color of the tag remains unchanged.


πŸ”’ Required privileges : Admin

Example URI

PUT /admin/global-tag-categories/categoryName/tags/tagName
URI Parameters
HideShow
categoryName
string (required) 

the name of a global tag category in DSS

tagName
string (required) 

the name of a tag of the category

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "engineering",
  "color": "#119911"
}
Response  200
HideShow
Headers
Content-Type: application/json

Delete tag
DELETE/admin/global-tag-categories/tags/{?deletionMode}{?reassignTo}

Delete a tag from a global tag category.


πŸ”’ Required privileges : Admin

Example URI

DELETE /admin/global-tag-categories/tags/?deletionMode=?reassignTo=
URI Parameters
HideShow
deletionMode
string (optional) Default: KEEP 

Specify how tagged objects are updated:

  • KEEP keeps the tags on tagged objects. They will just not appear as global tags anymore.

  • REMOVE removes the tags from tagged objects.

  • REASSIGN moves all tags to another category and update the tagged objects accordingly.

reassignTo
string (optional) 

When deletionMode=REASSIGN, name of the other tag to merge with the deleted one.

Response  200
HideShow
Headers
Content-Type: application/json

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

Audit trail

Trigger new audit trail log item
POST/admin/audit/{customMsgType}

Appends an entry to the audit trail. The JSON object given as the request body is put as customMsgParams in the created audit trail log entry.


πŸ”’ Required privileges : Run safe code

Example URI

POST /admin/audit/customMsgType
URI Parameters
HideShow
customMsgType
string (required) 

the customMsgType for the audit trail log entry

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "arbitraryKey1" : { ... },
    ...
}
Response  200
HideShow
Headers
Content-Type: text/plain

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

Licensing

List current license informations
GET/admin/licensing/status

Retrieve various informations about your license (expiration date, limits, feature scope, etc.)


πŸ”’ Required privileges : Admin

Example URI

GET /admin/licensing/status
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "base": {
        "licenseContent": {
            "licensee": {
                "email": "[email protected]",
                "company": "ACME Inc.",
                "name": "John Doe"
            },
            "dssMode": "ON_PREMISE_DISCONNECTED",
            "instanceId": "ab7cdefg",
            "licenseKind": "COMMUNITY",
            "licenseId": "iJKLMnoP4qrSTUvw",
            "properties": {
                "automationFeaturesVersion": "2018-1"
            },
            "communityEdition": "true"
        },
        "hasLicense": true,
        "valid": true,
        "expired": false,
        "expiresOn": 0,
        "ceEntrepriseTrial": false,
        "ceEntrepriseTrialUntil": 0,
        "community": true,
        "wasCEEntrepriseTrial": false,
        "ceInstanceId": "sg7jbvoz",
        "ceRegistrationEmail": "[email protected]",
        "userProfiles": [
            "DESIGNER"
        ]
    },
    "limits": {
        "licensedProfiles": {
            "DESIGNER": {
                "profile": "DESIGNER",
                "demotesFrom": [],
                "licensedLimit": 3,
                "mayAdmin": true,
                "mayPython": true,
                "mayScala": true,
                "mayR": true,
                "mayVisualML": true,
                "mayReadProjectContent": true,
                "mayWriteProjectContent": true,
                "mayWriteDashboards": true
            }
        },
        "profileLimits": {
            "DESIGNER": {
                "profile": "DESIGNER",
                "licensed": {
                    "profile": "DESIGNER",
                    "demotesFrom": [],
                    "licensedLimit": 3,
                    "mayAdmin": true,
                    "mayPython": true,
                    "mayScala": true,
                    "mayR": true,
                    "mayVisualML": true,
                    "mayReadProjectContent": true,
                    "mayWriteProjectContent": true,
                    "mayWriteDashboards": true
                },
                "directCount": 1,
                "demotedToOther": 0,
                "countWithDemotedTo": 1,
                "demotedTo": [],
                "demotedFromOther": 0,
                "demotedFrom": [],
                "limitWithDemoted": 0,
                "overQuota": 0
            }
        },
        "fallbackProfile": "DESIGNER"
    },
    "features": {
        "limitedEditionString": "Free Edition",
        "allowedDatasetTypes": [
            "S3",
            "SCP",
            "FTP",
            "Greenplum",
            "PostgreSQL",
            "Cassandra",
            "Netezza",
            "Twitter",
            "ElasticSearch",
            "MySQL",
            "Snowflake",
            "JDBC",
            "StatsDB",
            "Filesystem",
            "Oracle",
            "UploadedFiles",
            "FilesInFolder",
            "Azure",
            "BigQuery",
            "JobsDB",
            "HDFS",
            "SFTP",
            "HTTP",
            "Inline",
            "Teradata",
            "Redshift",
            "hiveserver2",
            "GCS",
            "SAPHANA",
            "Vertica",
            "MongoDB",
            "SQLServer"
        ],
        "allowedConnectionTypes": [
            "FTP",
            "Greenplum",
            "PostgreSQL",
            "Cassandra",
            "Netezza",
            "Twitter",
            "ElasticSearch",
            "EC2",
            "MySQL",
            "Snowflake",
            "JDBC",
            "StatsDB",
            "Filesystem",
            "Oracle",
            "UploadedFiles",
            "FilesInFolder",
            "Azure",
            "BigQuery",
            "JobsDB",
            "HDFS",
            "SSH",
            "HTTP",
            "Inline",
            "Teradata",
            "Redshift",
            "hiveserver2",
            "GCS",
            "SAPHANA",
            "Vertica",
            "MongoDB",
            "SQLServer"
        ],
        "ldapAllowed": false,
        "ssoAllowed": false,
        "userSecurityAllowed": false,
        "multiUserSecurityAllowed": false,
        "sparkAllowed": false,
        "sparkMLLibAllowed": false,
        "apiNodeAllowed": false,
        "lockedTracking": false,
        "forbiddenTracking": false,
        "bundlesAllowed": false,
        "advancedScenarioStepsAllowed": true,
        "temporalTriggerAllowed": false,
        "allScenarioTriggersAllowed": false,
        "allScenarioReportersAllowed": false,
        "advancedMetricsChecksAllowed": false,
        "modelsRawSQLExport": false,
        "modelsPMMLExport": false,
        "modelsJarExport": false
}

Set current license
POST/admin/licensing/license

Set DSS license


πŸ”’ Required privileges : Admin

Example URI

POST /admin/licensing/license
Request
HideShow
Headers
Content-Type: application/json
Body
...content of the license file provided by Dataiku...
Response  200
HideShow
Headers
Content-Type: text/plain

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"
}

Model Comparisons

Model Comparisons

List
GET/projects/{projectKey}/modelcomparisons

Retrieves the list of the model comparisons


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of a project

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {
        "projectKey": "PROJECTKEY",
        "id":"MyId",
        "displayName": "Display Name",
        "predictionType": "BINARY_CLASSIFICATION",
        "comparedModels": [
            {
                "refId": "S-PROJECTKEY-SMID-VERSIONID",
                ...
            },
            ...
        ]
    },
    {
        "projectKey": "PROJECTKEY",
        "id":"MyOtherId",
        "displayName": "Another Display Name",
        "predictionType": "BINARY_CLASSIFICATION",
        "comparedModels": [
            {
                "refId": "S-PROJECTKEY-SMID-VERSIONID",
                ...
            },
            ...
        ]
    }
]

Get
GET/projects/{projectKey}/modelcomparisons/{mcId}

Retrieves a model comparison


πŸ”’ Required privileges : READ_CONF

Example URI

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

the key of a project

mcId
string (required) Example: MC_ID

the id of a model comparison

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "projectKey": "PROJECTKEY",
    "id":"MyId",
    "displayName": "Display Name",
    "predictionType": "BINARY_CLASSIFICATION",
    "comparedModels": [
        {
            "refId": "S-PROJECTKEY-SMID-VERSIONID",
...
        },
...
    ]
}

Create a model comparison
POST/projects/{projectKey}/modelcomparisons

Create a model comparison


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the key of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "predictionType": "BINARY_CLASSIFICATION",
    "displayName": "Display Name",
    "projectKey": "PROJECTKEY",
    "comparedModels": [
        {
            refId: "S-PROJECTKEY-SMID-SMVID"
        },
        ...
    ]
}
Response  200
HideShow
Body
{
  "id": "gEnErAtEd",
  "msg": "Created model comparison <generated id> (named Display Name) in PROJECTKEY"
}

Update
PUT/projects/{projectKey}/modelcomparisons/

Modify a model comparison


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the key of a project

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "predictionType": "BINARY_CLASSIFICATION",
    "displayName": "Display Name",
    "projectKey": "PROJECTKEY",
    "comparedModels": [
        {
            refId: "S-PROJECTKEY-SMID-SMVID"
        },
        ...
    ]
}
Response  200
HideShow
Body
{
  "msg": "Updated model comparison PROJECTKEY.mcId"
}

Delete
DELETE/projects/{projectKey}/modelcomparisons/{mcId}

Delete a model comparison


πŸ”’ Required privileges : WRITE_CONF

Example URI

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

the key of a project

mcId
string (required) Example: MC_ID

the id of a model comparison

Response  200
HideShow
Body
{
  "msg": "Deleted model comparison PROJECTKEY.mcId"
}

Feature Store

Feature Store

List Feature Groups
GET/publicapi/feature-store/feature-groups

Retrieves the list of the feature groups of projects on which the user has at least read permission

Example URI

GET /publicapi/feature-store/feature-groups
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    {
        "projectKey": "PROJECTKEY",
        "name": "dataset_name
    },
    ...
]

Generated by aglio on 15 Dec 2023