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"

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

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

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

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_{: .parameter-name} string	An identifier of the response.
statusCode{: .parameter-name} integer	The HTTP response code.
exception{: .parameter-name} string	An explanation of the problem.
message{: .parameter-name} 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

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

POST /v1/authorize

Request

Request Body

Required*

loginCredentials

Example request

curl -k -X POST -H "cache-control: no-cache" -H "Content-Type: application/json" -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

Status 200

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

Returns all users in the cluster.

GET /v1/users

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Example request

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

Create a user account for the cluster.

POST /v1/users

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Request Body

createUserParamsBody

The new user.

Examples:

View

Example request

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

Status 200

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

Get details about one user.

GET /v1/users/{user_name}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

user_name
Required*
string
The user name.

Example request

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

Update information about a user account.

PUT /v1/users/{user_name}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

user_name
Required*
string
The user name.

Request Body

updateUserParamsBody

The updated user information.

Example request

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

Status 200

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

Delete a user from the cluster.

DELETE /v1/users/{user_name}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

user_name
Required*
string
The user name.

Example request

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

Status 200

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

Returns the user roles in the cluster.

GET /v1/roles

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Example request

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

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

POST /v1/roles

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Request Body

createRoleParamsBody

Information for creating a role

Examples:

View

Example request

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

Status 200

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

Get details about one role.

GET /v1/roles/{role_id}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

role_id
Required*
string
The identifier of the role.

Example request

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

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

PUT /v1/roles/{role_id}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

role_id
Required*
string
The identifier of the role.

Request Body

updateRoleParamsBody

The updated role information.

Examples:

View

Example request

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

Status 200

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

Delete a role from the cluster.

DELETE /v1/roles/{role_id}

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Path Parameters

role_id
Required*
string
The identifier of the role.

Example request

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

Status 200

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

Returns all permissions in the cluster.

GET /v1/permissions

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Example request

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

Status 200

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

Change the logged in user's password.

POST /v1/changepassword

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Form Parameters

current_password
Required*
string
Current password.
new_password
Required*
string
New password.

Example request

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

Status 200

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

Get details about the logged in user.

GET /v1/me

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Example request

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

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

PUT /v1/me

Request

Custom Headers

Authorization
string
The bearer token associated with a user name.

Request Body

updateMeParamsBody

The updated user information.

Example request

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

Status 200

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

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

GET /v1/monitor

Request

No Request Parameters

This method does not accept any request parameters.

Example request

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

Status 200

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

GET /ae/{instance_id}/v2/jobs

Request

Path Parameters

instance_id
Required*
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.

POST /ae/{instance_id}/v2/jobs

Request

Path Parameters

instance_id
Required*
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 /ae/{instance_id}/v2/jobs/{job_id}

Request

Path Parameters

instance_id
Required*
string
instance id
job_id
Required*
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.

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

Request

Path Parameters

instance_id
Required*
string
instance id
job_id
Required*
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