Cloud operations API reference

Find detailed information about the cloud operations APIs.

The complete OpenAPI specification for the APIs is included in the following topics. The APIs that are enabled for your cloud subscription might differ. To check which APIs are enabled, use the API test tool.

Note: These operations do not apply to IBM® Operational Decision Manager on Cloud.

Accessing the REST API test tool

You can access the Swagger user interface at https://hostname/api/explorer, where hostname is the name of your offering subscription. For example, https://vhost123.mycloud.com/api/explorer. This interface exposes a view of the available endpoints, their documentation, and a Try it out button to test each endpoint.

To directly access the OpenAPI specification, you can use the following REST API call:

GET /api/docs

The call returns a JSON object that contains the OpenAPI specification of the APIs that are enabled on your subscription.

Authentication

All endpoints require authentication. You can authenticate by using basic authentication, with your cloud subscription user name and password. For example:

curl https://tenant_name.automationcloud.ibm.com/instance/services/users --user username@company_name.com:password

Note: In the Swagger user interface, you might see a Image shows warning icon

warning icon in some of the REST API methods. When you click this warning, a window opens asking for your login credentials. If you are authenticated to the cloud portal, you do not need to authenticate again, and you can disregard this warning.

As an alternative to basic authentication, you can use service credentials to authenticate to the application. For more information, see Authenticating client applications.

Filtering and pagination

You can use pagination with explore methods that return collections of objects, such as /users. By default, all elements of the collection are returned, but you can specify a page size and a page number to retrieve only a subset of the collection. For example:

curl https://tenant_name.automationcloud.ibm.com/instance/services/users?offset=2&size=20 --user username@company_name.com:password

You can also filter the object collection by including API-specific parameters to the call. To find out which parameters you can use, refer to the documentation for each of the APIs.

Errors

Conventional HTTP response codes are used to indicate the success or failure of an API request. When an error occurs, the body of the HTTP response always contains a JSON error object with an error code, a reason, and a reference. For example:

{
  "error_number": "CWMGG0006E",
  "error_message": "CWMGG0006E: The value 'username@company_name.com' is invalid for the 'member_id' parameter.",
  "error_message_parameters": [
    "username@company_name.com",
    "member_id"
  ],
  "incident_id": "62d28e96-3059-433a-911d-f9109a7fc93a"
}