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_ 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_ . |
Related APIs
- 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
Methods
Get authorization token
Generate a bearer token from your Cloud Pak for Data credentials.
POST /v1/authorize
Request
IBM Cloud Pak for Data username.
IBM Cloud Pak for Data password.
IBM Cloud Pak for Data API key.
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
The identifier of the response.
The explanation of the
_messageCode_
.The bearer token associated with a user name.
Example:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Status Code
Success
Bad Request
Unauthorized
Internal error
{ "_messageCode_": "200", "message": "Success", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }
Request
Custom Headers
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Internal error
{ "_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" } ] }
Request
Custom Headers
The bearer token associated with a user name.
The new user.
The name that is displayed for this user.
The user's email address.
The user name.
The password
The roles assigned to the 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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Internal error
{ "_messageCode_": "200", "message": "Success", "User": { "ID": "1001" } }
Request
Custom Headers
The bearer token associated with a user name.
Path Parameters
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Not Found
Internal error
{ "_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" } }
Request
Custom Headers
The bearer token associated with a user name.
Path Parameters
The user name.
The updated user information.
The roles assigned to the user.
The status of the user's access to the web client.
Allowable values: [
pending
,approved
]The name that is displayed for this user.
The user's email address.
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Not found.
Internal error
{ "_messageCode_": "200", "message": "Success" }
Request
Custom Headers
The bearer token associated with a user name.
Path Parameters
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Not Found
Internal error
{ "_messageCode_": "200", "message": "Success" }
Request
Custom Headers
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
message code
Example:
200
message
Example:
Success
Status Code
Success
Unauthorized
Internal error
{ "_messageCode_": "200", "message": "Success", "Roles": { "ID": "zen_administrator_role", "description": "Administrator role", "permissions": [ "string" ], "role_name": "Administrator" } }
Request
Custom Headers
The bearer token associated with a user name.
Information for creating a role
The permissions associated with the role.
Name for the role.
Description of the 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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Internal error
{ "_messageCode_": "200", "message": "Success" }
Request
Custom Headers
The bearer token associated with a user name.
Path Parameters
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Not Found
Internal error
{ "_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}
Request
Custom Headers
The bearer token associated with a user name.
Path Parameters
The identifier of the role.
The updated role information.
The permissions associated with the role.
Display name of role e.g. Administrator
The description of the role.
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Not Found
Internal error
{ "_messageCode_": "200", "message": "Success" }
Request
Custom Headers
The bearer token associated with a user name.
Path Parameters
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Not Found
Internal error
{ "_messageCode_": "200", "message": "Success" }
Request
Custom Headers
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
The identifier of the response.
The explanation of the
_messageCode_
.The array of permissions.
Status Code
Success
Unauthorized
Internal error
{ "_messageCode_": "200", "message": "Success", "Permissions": [] }
Request
Custom Headers
The bearer token associated with a user name.
Form Parameters
Current password.
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Internal error
{ "_messageCode_": "200", "message": "Success" }
Request
Custom Headers
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Internal error
{ "_messageCode_": "200", "message": "Success", "UsersInfo": [ { "displayName": "admin", "email": "admin@example.com", "permissions": [ "string" ], "role": "admin", "uid": "1001", "username": "Admin" } ] }
Request
Custom Headers
The bearer token associated with a user name.
The updated user information.
The name that is displayed for this user.
The user's email address.
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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Unauthorized
Internal error
{ "_messageCode_": "200", "message": "Success" }
Check server status
Indicates whether your Cloud Pak for Data API server is running. is running
GET /v1/monitor
Request
No 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
The identifier of the response.
The explanation of the
_messageCode_
.
Status Code
Success
Error
{ "_messageCode_": "200", "message": "Success" }
Request
Path Parameters
instance id
Response
Job detail response
uuid of job
Job state
Status Code
List of running jobs
Instance id or api key not provided in the header
Instance id or api key provided but not authorized to create instance
Internal error occured
Job creation timed out
No Sample Response
Request
Path Parameters
instance id
Required job details
List of string arguments for spark application
In case of Scala it is the path to jar containing the Main class and in case of python/R it is the path to the script file
In case of scala the Main class of your application else org.apache.spark.deploy.SparkSubmit
(Optional) Id of Watson Studio Enviornment that represents the Engine(cluster) definition. Either environment or Engine needs to be provided but not both.
(Optional) - Runtime Engine information. Either environment or Engine needs to be provided but not both.
(Optional) These parameters are passed when user want to give home_volume details
Supported value is cos.
crn of the cos instance to be used
cos bucket's region
cos instance's api key to connect
cos bucket's to be used as instance home
HMAC style keys to connect
access_key_id for cos
secret_access_key to connect
cos_hmac_keys
cos_bucket_details
instance_home
Response
Job detail response
uuid of job
Job state
Status Code
The metadata about the newly created job.
Instance id or api key not provided in the header
Instance id or api key provided but not authorized to create instance
Internal error occured
Job creation timed out
No Sample Response
Request
Path Parameters
instance id
job uuid
Response
Job detail response
uuid of job
Job state
Status Code
Get state of a job
Instance id or job id not valid
Instance id or api key not provided in the header
Instance id or api key provided but not authorized to create instance
Internal error occured
Job creation timed out
No Sample Response
Request
Path Parameters
instance id
job uuid
Response
Status Code
Job deleted
Instance id or api key not provided in the header
Instance id or api key provided but not authorized to create instance
Job id not found
Internal error occured
Job deletion timed out