IBM Cloud Pak for Data Platform API

Introduction

Last updated: 2020-09-02

The IBM® Cloud Pak for Data Platform API connects to your Cloud Pak for Data platform to manage your user account. Administrators can also manage the users who have access to the platform, manage roles, and monitor the status of the platform.

Authentication

To authenticate to the API, you pass an access token in an Authorization header. The token is associated with a user name. To generate an access token, call the Get authorization token method.

Generating an access token. The response includes a token property.

Replace {cpd_cluster_host} and {port} with the details for the service instance. Replace {username} and {password} with your IBM Cloud Pak for Data credentials.

curl -k -X POST -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize"

curl -k -X POST -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize"

Authenticating to the API. Replace {token} with your details.

curl -H "Authorization: Bearer {token}" "https://{cpd_cluster_host}{:port}/v1/{method}"

curl -H "Authorization: Bearer {token}" "https://{cpd_cluster_host}{:port}/v1/{method}"

Service endpoint

The service endpoint is based on your IBM Cloud Pak deployment URL.

https://{cpd_cluster_host}{:port}/icp4d-api/v1/{method}

For example, if your instance is deployed at https://www.example.com:31843, you can access the APIs at https://www.example.com:31843/icp4d-api/v1/{method}.

Example

curl -H "Authorization: Bearer {token}" -X {request_method} "https://{cpd_cluster_host}{:port}/icp4d-api/v1/{method}"

curl -H "Authorization: Bearer {token}" -X {request_method} "https://{cpd_cluster_host}{:port}/icp4d-api/v1/{method}"

Disabling SSL verification

All Cloud Pak for Data services use Secure Sockets Layer (SSL) (or Transport Layer Security (TLS)) for secure connections between the client and server. The connection is verified against the local certificate store to ensure authentication, integrity, and confidentiality.

If you use a self-signed certificate, you need to disable SSL verification to make a successful connection.

Enabling SSL verification is highly recommended. Disabling SSL jeopardizes the security of the connection and data. Disable SSL only if absolutely necessary, and take steps to enable SSL as soon as possible.

To disable SSL verification for a curl request, use the --insecure (-k) option with the request.

Example that disables SSL verification

curl -k -X {request_method} -H "Authorization: Bearer {token}" "{url}/v1/{method}"

curl -k -X {request_method} -H "Authorization: Bearer {token}" "{url}/v1/{method}"

Error handling

IBM Cloud Pak for Data uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.

ErrorResponse

Name	Description
_messageCode_ string	An identifier of the response.
statusCode integer	The HTTP response code.
exception string	An explanation of the problem.
message string	An explanation of the `_messageCode_`.

IBM Cloud Pak for Data docs

Watson Data API: Manage data-related assets and the people who need to use these assets.
Watson Machine Learning API: Train, store, deploy, and score your models.
Master Data Connect API: Get access to your organization's most trusted master data.
Watson OpenScale API: Measure the outcomes of your AI models.
Apache Spark jobs API: Run Spark jobs or applications on your cluster without installing Watson Studio.
Watson APIs for Cloud Pak for Data
- Watson Assistant API: v2 | v1
- Watson Discovery API v1
- Watson API Kit
  - IBM Watson Speech to Text API
  - IBM Watson Text to Speech API

Get authorization token

Generate a bearer token from your Cloud Pak for Data credentials.

POST /v1/authorize

/v1/authorize

Request

Request Body

loginCredentials

curl -k -X POST -H "cache-control: no-cache" -d "{\"username\":\"{username}\",\"password\":\"{password}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/authorize"

Response

Response Body

loginResponse

Status Code

200
Success
400
Bad Request
401
Unauthorized
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }

Get all users

Returns all users in the cluster.

GET /v1/users

/v1/users

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users"

Response

Response Body

getAllUsersResponse

Status Code

200
Success
401
Unauthorized
500
Internal error

Example responses

Status 200

{
  "_messageCode_": "200",
  "message": "Success",
  "UsersInfo": [
    {
      "approval_status": "approved",
      "authenticator": "default",
      "created_timestamp": "2018-10-08T21:53:14.855Z",
      "current_account_status": "enabled",
      "displayName": "admin",
      "email": "admin@example.com",
      "last_modified_timestamp": "2018-10-08T21:53:14.855Z",
      "permissions": [
        "string"
      ],
      "role": "Admin",
      "uid": "1001",
      "user_roles": [
        "string"
      ],
      "username": "Admin"
    }
  ]
}
{
  "_messageCode_": "200",
  "message": "Success",
  "UsersInfo": [
    {
      "approval_status": "approved",
      "authenticator": "default",
      "created_timestamp": "2018-10-08T21:53:14.855Z",
      "current_account_status": "enabled",
      "displayName": "admin",
      "email": "admin@example.com",
      "last_modified_timestamp": "2018-10-08T21:53:14.855Z",
      "permissions": [
        "string"
      ],
      "role": "Admin",
      "uid": "1001",
      "user_roles": [
        "string"
      ],
      "username": "Admin"
    }
  ]
}

Create user

Create a user account for the cluster.

POST /v1/users

/v1/users

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Request Body

createUserParamsBody

The new user.

curl -k -X POST -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"user_name\":\"{username}\",\"password\":\"{password}\",\"displayName\":\"{display_name}\",\"user_roles\":\"{user_roles}\",\"email\":\"{email}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users"

Response

Response Body

createUserSuccessResponse

Status Code

200
Success
401
Unauthorized
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success", "User": { "ID": "1001" } }

Get user information

Get details about one user.

GET /v1/users/{user_name}

/v1/users/{user_name}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

user_name
string
The user name.

curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users/{user_name}"

Response

Response Body

getUserResponse

Status Code

200
Success
401
Unauthorized
404
Not Found
500
Internal error

Example responses

Status 200

{
  "_messageCode_": "200",
  "message": "Success",
  "UserInfo": {
    "approval_status": "approved",
    "authenticator": "default",
    "created_timestamp": "2018-10-08T21:53:14.855Z",
    "current_account_status": "enabled",
    "displayName": "admin",
    "email": "admin@example.com",
    "last_modified_timestamp": "2018-10-08T21:53:14.855Z",
    "permissions": [
      "string"
    ],
    "role": "Admin",
    "uid": "1001",
    "user_roles": [
      "string"
    ],
    "username": "Admin"
  }
}
{
  "_messageCode_": "200",
  "message": "Success",
  "UserInfo": {
    "approval_status": "approved",
    "authenticator": "default",
    "created_timestamp": "2018-10-08T21:53:14.855Z",
    "current_account_status": "enabled",
    "displayName": "admin",
    "email": "admin@example.com",
    "last_modified_timestamp": "2018-10-08T21:53:14.855Z",
    "permissions": [
      "string"
    ],
    "role": "Admin",
    "uid": "1001",
    "user_roles": [
      "string"
    ],
    "username": "Admin"
  }
}

Update user details

Update information about a user account.

PUT /v1/users/{user_name}

/v1/users/{user_name}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

user_name
string
The user name.

Request Body

updateUserParamsBody

The updated user information.

curl -k -X PUT -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"displayName\":\"{display_name}\", \"user_roles\":\"{user_roles}\", \"email\":\"{email}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users/{user_name}"

Response

Response Body

successResponse

Status Code

200
Success
401
Unauthorized
404
Not found.
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success" }

Delete user

Delete a user from the cluster.

DELETE /v1/users/{user_name}

/v1/users/{user_name}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

user_name
string
The user name.

curl -k -X DELETE -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/users/{user_name}"

Response

Response Body

successResponse

Status Code

200
Success
401
Unauthorized
404
Not Found
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success" }

List all roles

Returns the user roles in the cluster.

GET /v1/roles

/v1/roles

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles"

Response

Response Body

getAllRolesResponse

Status Code

200
Success
401
Unauthorized
500
Internal error

Example responses

Status 200

{
  "_messageCode_": "200",
  "message": "Success",
  "Roles": {
    "ID": "zen_administrator_role",
    "description": "Administrator role",
    "permissions": [
      "string"
    ],
    "role_name": "Administrator"
  }
}
{
  "_messageCode_": "200",
  "message": "Success",
  "Roles": {
    "ID": "zen_administrator_role",
    "description": "Administrator role",
    "permissions": [
      "string"
    ],
    "role_name": "Administrator"
  }
}

Create role

If the provided roles do not meet your needs, you can create other roles.

POST /v1/roles

/v1/roles

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Request Body

createRoleParamsBody

Information for creating a role

curl -k -X POST -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"role_name\":\"{name}\",\"description\":\"{description}\",\"permissions\":\"{permissions}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles"

Response

Response Body

successResponse

Status Code

200
Success
401
Unauthorized
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success" }

Get role information

Get details about one role.

GET /v1/roles/{role_id}

/v1/roles/{role_id}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

role_id
string
The identifier of the role.

curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles/{role_id}"

Response

Response Body

getRoleResponse

Status Code

200
Success
401
Unauthorized
404
Not Found
500
Internal error

Example responses

Status 200

{
  "_messageCode_": "200",
  "message": "Success",
  "RoleInfo": {
    "ID": "zen_administrator_role",
    "description": "Administrator role",
    "permissions": [
      "string"
    ],
    "role_name": "Administrator"
  }
}
{
  "_messageCode_": "200",
  "message": "Success",
  "RoleInfo": {
    "ID": "zen_administrator_role",
    "description": "Administrator role",
    "permissions": [
      "string"
    ],
    "role_name": "Administrator"
  }
}

Update role

Update the name, description, and permissions associated with a role.

PUT /v1/roles/{role_id}

/v1/roles/{role_id}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

role_id
string
The identifier of the role.

Request Body

updateRoleParamsBody

The updated role information.

curl -k -X PUT -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"role_name\":\"{role_name}\",\"description\":\"{role_description}\",\"permissions\":\"{permissions}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles/{role_id}"

Response

Response Body

successResponse

Status Code

200
Success
401
Unauthorized
404
Not Found
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success" }

Delete role

Delete a role from the cluster.

DELETE /v1/roles/{role_id}

/v1/roles/{role_id}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

role_id
string
The identifier of the role.

curl -k -X DELETE -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/roles/{role_id}"

Response

Response Body

successResponse

Status Code

200
Success
401
Unauthorized
404
Not Found
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success" }

List all permissions

Returns all permissions in the cluster.

GET /v1/permissions

/v1/permissions

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/permissions"

Response

Response Body

getPermissionsResponse

Status Code

200
Success
401
Unauthorized
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success", "Permissions": [] }

Change my password

Change the logged in user's password.

POST /v1/changepassword

/v1/changepassword

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Form Parameters

current_password
string
Current password.
new_password
string
New password.

curl -k -X POST -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"current_password\":\"{CURRENT_PASSWORD}\", \"new_password\":\"{NEW_PASSWORD}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/changepassword"

Response

Response Body

successResponse

Status Code

200
Success
401
Unauthorized
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success" }

Get my account information

Get details about the logged in user.

GET /v1/me

/v1/me

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/me"

Response

Response Body

getMeResponse

Status Code

200
Success
401
Unauthorized
500
Internal error

Example responses

Status 200

{
  "_messageCode_": "200",
  "message": "Success",
  "UsersInfo": [
    {
      "displayName": "admin",
      "email": "admin@example.com",
      "permissions": [
        "string"
      ],
      "role": "admin",
      "uid": "1001",
      "username": "Admin"
    }
  ]
}
{
  "_messageCode_": "200",
  "message": "Success",
  "UsersInfo": [
    {
      "displayName": "admin",
      "email": "admin@example.com",
      "permissions": [
        "string"
      ],
      "role": "admin",
      "uid": "1001",
      "username": "Admin"
    }
  ]
}

Update my information

Update the display name or email address for the logged in user.

PUT /v1/me

/v1/me

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Request Body

updateMeParamsBody

The updated user information.

curl -k -X PUT -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"displayName\":\"{display_name \",\"email\":\"{email}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/me"

Response

Response Body

successResponse

Status Code

200
Success
401
Unauthorized
500
Internal error

Example responses

{ "_messageCode_": "200", "message": "Success" }

Check server status

Indicates whether your Cloud Pak for Data API server is running. is running

GET /v1/monitor

/v1/monitor

Request

No Request Parameters

This method does not accept any request parameters.

curl -k -X GET -H "Authorization: Bearer {token}" -H "cache-control: no-cache" -d "{\"displayName\":\"{display_name \",\"email\":\"{email}\"}" "https://{cpd_cluster_host}{:port}/icp4d-api/v1/monitor"

Response

Response Body

successResponse

Status Code

200
Success
default
Error

Example responses

{ "_messageCode_": "200", "message": "Success" }

List the JSON data for all currently running jobs for a instance

GET /ae/{instance_id}/v2/jobs

/ae/{instance_id}/v2/jobs

Request

Path Parameters

instance_id
string
instance id

Response

Response Body

JobResponse[]

Job detail response

Status Code

200
List of running jobs
401
Instance id or api key not provided in the header
403
Instance id or api key provided but not authorized to create instance
500
Internal error occured
504
Job creation timed out

No Sample Response

This method does not specify any sample responses.

Start a job and return the uuid

POST /ae/{instance_id}/v2/jobs

/ae/{instance_id}/v2/jobs

Request

Path Parameters

instance_id
string
instance id

Request Body

Job

Required job details

Response

Response Body

JobResponse

Job detail response

Status Code

201
The metadata about the newly created job.
401
Instance id or api key not provided in the header
403
Instance id or api key provided but not authorized to create instance
500
Internal error occured
504
Job creation timed out

No Sample Response

This method does not specify any sample responses.

Get the JSON data for a job

GET /ae/{instance_id}/v2/jobs/{job_id}

/ae/{instance_id}/v2/jobs/{job_id}

Request

Path Parameters

instance_id
string
instance id
job_id
string
job uuid

Response

Response Body

JobResponse

Job detail response

Status Code

200
Get state of a job
400
Instance id or job id not valid
401
Instance id or api key not provided in the header
403
Instance id or api key provided but not authorized to create instance
500
Internal error occured
504
Job creation timed out

No Sample Response

This method does not specify any sample responses.

Kill a job

DELETE /ae/{instance_id}/v2/jobs/{job_id}

/ae/{instance_id}/v2/jobs/{job_id}

Request

Path Parameters

instance_id
string
instance id
job_id
string
job uuid

Response

Status Code

204
Job deleted
401
Instance id or api key not provided in the header
403
Instance id or api key provided but not authorized to create instance
404
Job id not found
500
Internal error occured
504
Job deletion timed out

No Sample Response

This method does not specify any sample responses.

Introduction

Authentication

Service endpoint

Disabling SSL verification

Error handling

Related information

Related APIs

Methods

Get authorization token

Request

Request Body

username

password

api_key

Response

Response Body

_messageCode_

message

token

Status Code

200

400

401

500

Get all users

Request

Custom Headers

Authorization

Response

Response Body

_messageCode_

message

UsersInfo

Status Code

200

401

500

Create user

Request

Custom Headers

Authorization

Request Body

displayName

email

user_name

password

user_roles

Response

Response Body

_messageCode_

message

User

Status Code

200

401

500

Get user information

Request

Custom Headers

Authorization

Path Parameters

user_name

Response

Response Body

_messageCode_

message

UserInfo

Status Code

200

401

404

500

Update user details

Request

Custom Headers

Authorization

Path Parameters

user_name

Request Body

user_roles