IBM Cloud API Docs

Introduction

IBM® MQ is an enterprise grade messaging middleware service that gives independent and potentially non-concurrent applications secure messaging capabilities, such as point-to-point and publish/subscribe models.

IBM MQ on IBM Cloud enables you to quickly and easily deploy queue managers in the cloud and connect your applications to them, providing reliable data transfer between different parts of your enterprise application landscape.

Use the MQ on Cloud API to Get, Create, Delete and Configure MQ resources. Queue manager, User, App and Certificate interfaces enable convenient programmatic control of MQ on Cloud resource lifecycles and day two operations.

For more information about how to use MQ on Cloud, see: Getting started.

Note: API access is restricted to users of the reserved deployment plan.

Endpoint URLs

The base URLs for MQ on IBM Cloud API endpoints are specific to the region of your Service Instance. For example:

https://api.private.<region>.mq2.cloud.ibm.com

For a list of regions and their short-names, see: Deployment Locations.

Authentication

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token, and service instance GUID (ID) in API requests.

You can use the IBM Cloud CLI to quickly generate your personal Cloud IAM access token.

  1. Log in to IBM Cloud with the IBM Cloud CLI.

    ibmcloud login
    

    If the login fails, run the ibmcloud login --sso command to try again. The --sso parameter is required when you log in with a federated ID. If this option is used, go to the link listed in the CLI output to generate a one-time pass code.

  2. Select the account, region, and resource group that contain your provisioned instance of MQ on IBM Cloud.

  3. Run the following command to retrieve your Cloud IAM access token.

    ibmcloud iam oauth-tokens
    

    The following truncated example shows a retrieved IAM token.

    IAM token: Bearer eyJraWQiOiIyM...
    

To retrieve your Service Instance GUID:

Run the following command substituting in your Service Instance name here {service-instance-name} and extract the value of the field guid.

ibmcloud resource service-instance {service-instance-name} --output JSON

You can build your API request by pairing a service endpoint with your authentication credentials. For example, if you created a MQ on Cloud service instance for the eu-de region, use the following endpoint and API headers to retrieve queue managers in your service instance:

curl -X GET \
    -H "Accept: application/json" \
    -H "Authorization: Bearer <access_token>" \
    "https://api.private.eu-de.mq2.cloud.ibm.com/v1/<guid>/queue_managers"

Replace <access_token> with your IBM Cloud IAM token, and <guid> with the Service Instance GUID (ID) that identifies your MQ on Cloud service instance.

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker.

For more information about how to track MQ activity, see Activity Tracker events.

Error handling

This API 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 can't be resolved by the user. The following table describes the HTTP error codes.

HTTP Error Code Description Recovery
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud to get an IAM token and try again. If this error persists, contact the account owner to check your permissions.
404 Not Found The requested resource could not be found or you do not have permission to discover the requested resource. If this error persists, contact the account owner to check your permissions.
405 Method Not Allowed The provided HTTP method is not supported by the endpoint. Review your chosen method against the API documentation.
409 Conflict A resource with this name already exists or is already in the requested state. For a new resource, choose a unique name.
429 Too Many Requests Overuse of the API. Inspect the response headers to find the retry-after time.
500 Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request. If this error persists, contact the support team.
503 Service unavailable MQ on Cloud is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Understanding error models

This API follows IBM Cloud API Handbook Errors standards, ensuring consistency across error models. Where possible, error responses will include information to assist in understanding the root cause of the error. For example:

{
  "errors": [
    {
      "code": "bad_request",
      "message": "Bad request for service instance 6b79b864-a049-4d9e-862d-99bc79759396, channel [CLOUD.APP.FAKE] is not configurable as an AMS channel for target queuemanager",
      "more_info": "https://cloud.ibm.com/apidocs/mq-on-cloud#set-certificate-ams-channels",
      "target": {
        "type": "field",
        "name": "channels"
      }
    }
  ],
  "trace": "afe0399f-d99a-4723-a5f1-6deb1e8e1703",
  "status_code": 400
}

At a minimum, the code, message, trace and status_code fields will be provided. If you need to raise a support ticket for an error, include these fields in the support ticket to enable timely debug and resolution. If more information is available, such as which field is incomplete, invalid or otherwise erroneous, the more_info and target fields will be populated to focus the user towards the problem area(s).

Pagination

Some API requests might return many results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

  • /v1/{sid}/queue_managers
  • /v1/{sid}/users
  • /v1/{sid}/applications

The default page size is 25 objects. To use a different page size, use the limit query parameter. The pagination strategy in use is limit and offset.

For any request that uses pagination, the response includes First and where applicable Next and Previous objects containing URLs to make subsequent requests:

  • First: The object containing the URL for requesting the first page of results
  • Next: The object containing the URL for requesting the next page of results. The Next field is omitted if there are no more results
  • Previous: The object containing the URL for requesting the previous page. The Previous field is omitted if the response is the first page (offset=0)

These URLs retain the same limit parameter that was used for the initial request.

Rate limiting

Rate limits for API requests are enforced on a per-server basis. If the number of requests to the server reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

The response to each HTTP request includes headers that you can use to determine whether you are close to the rate limit:

  • Retry-after: The time to wait before trying the request again (in seconds)
  • X-Ratelimit-Limit: The total number of requests allowed within the time window
  • X-Ratelimit-Remaining: The number of requests remaining in the current time window
  • X-Ratelimit-Reset: The time the current timer expires (in UNIX epoch time)

HTTP status code 429 indicates that the rate limit has been exceeded.

Methods

Get the usage details

Get the usage details.

GET /v1/{service_instance_guid}/usage

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/usage'

Response

Usage details.

Status Code

  • Usage details for an account.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "vpc_entitlement": 4,
      "vpc_usage": 3.5
    }

Return configuration options (eg, available deployment locations, queue manager sizes)

Return configuration options (eg, available deployment locations, queue manager sizes).

GET /v1/{service_instance_guid}/options

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/options'

Response

Configuration options (eg, available deployment locations, queue manager sizes).

Status Code

  • Configuration options.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "locations": [
        "ibmcloud_eu_de"
      ],
      "sizes": [
        "xsmall",
        "small",
        "medium",
        "large"
      ],
      "versions": [
        "9.3.3_1"
      ]
    }

Create a new queue manager

Create a new queue manager.

POST /v1/{service_instance_guid}/queue_managers

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

Queue manager to add to the list.

  • curl -X POST -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{
      "size": "small",
      "name": "qmtest",
      "display_name": "qmTest",
      "location": "ibmcloud_eu_de"
    }' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/queue_managers'

Response

A URI for status that can be queried periodically to get the status of the queue manager.

Status Code

  • Returns url to track progress of the queue manager deployment.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Method not allowed

  • Conflict

  • Service Is Overused

  • Internal Server Error

  • Service Unavailable Error

Example responses
  • {
      "queue_manager_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers",
      "queue_manager_status_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/status",
      "queue_manager_id": "b8e1aeda078009cf3db74e90d5d42328"
    }

Get list of queue managers

Get a list of the queue manager summaries which exist in this service instance.

GET /v1/{service_instance_guid}/queue_managers

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

Query Parameters

  • Pagination offset.

    Possible values: 0 ≤ value ≤ 99999

    Default: 0

  • The numbers of resources to return.

    Possible values: 0 ≤ value ≤ 100

    Default: 25

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/queue_managers'

Response

A list of queue manager summaries.

Status Code

  • An object containing a list of queue managers.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "offset": 25,
      "limit": 25,
      "first": {
        "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers?limit=25"
      },
      "next": {
        "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers?offset=50&limit=25"
      },
      "previous": {
        "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers?offset=25&limit=25"
      },
      "queue_managers": [
        {
          "id": "b8e1aeda078009cf3db74e90d5d42328",
          "name": "testqm",
          "display_name": "Test QM",
          "location": "ibmcloud_us_south",
          "size": "xsmall",
          "status_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/status",
          "version": "9.3.2_2",
          "web_console_url": "https://web-testqm-fc4f.qm1.eu-de.mq.appdomain.cloud/ibmmq/console",
          "rest_api_endpoint_url": "https://web-testqm-fc4f.qm1.eu-de.mq.appdomain.cloud/ibmmq/rest/v3/messaging/qmgr/testqm/queues/<queue_name>/message",
          "administrator_api_endpoint_url": "https://web-testqm-fc4f.qm1.eu-de.mq.appdomain.cloud/ibmmq/rest/v3/admin/qmgr/testqm",
          "connection_info_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/connection_info",
          "date_created": "2023-07-19T14:46:05Z",
          "upgrade_available": false,
          "available_upgrade_versions_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/available_versions",
          "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328"
        }
      ]
    }

Get details of a queue manager

Get the details of a given queue manager.

GET /v1/{service_instance_guid}/queue_managers/{queue_manager_id}

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • The id of the queue manager to retrieve its full details.

    Possible values: length = 32, Value must match regular expression ^[0-9a-fA-F]{32}$

    Example: b8e1aeda078009cf3db74e90d5d42328

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/queue_managers/<queue_manager_id>'

Response

The details of the queue manager.

Status Code

  • Description of the queue manager.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "id": "b8e1aeda078009cf3db74e90d5d42328",
      "name": "testqm",
      "display_name": "Test QM",
      "location": "ibmcloud_us_south",
      "size": "xsmall",
      "status_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/status",
      "version": "9.3.2_2",
      "web_console_url": "https://web-testqm-fc4f.qm1.eu-de.mq.appdomain.cloud/ibmmq/console",
      "rest_api_endpoint_url": "https://web-testqm-fc4f.qm1.eu-de.mq.appdomain.cloud/ibmmq/rest/v3/messaging/qmgr/testqm/queues/<queue_name>/message",
      "administrator_api_endpoint_url": "https://web-testqm-fc4f.qm1.eu-de.mq.appdomain.cloud/ibmmq/rest/v3/admin/qmgr/testqm",
      "connection_info_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/connection_info",
      "date_created": "2023-07-19T14:46:05Z",
      "upgrade_available": false,
      "available_upgrade_versions_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/available_versions",
      "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328"
    }

Delete a queue manager

Delete a queue manager.

DELETE /v1/{service_instance_guid}/queue_managers/{queue_manager_id}

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • The id of the queue manager to retrieve its full details.

    Possible values: length = 32, Value must match regular expression ^[0-9a-fA-F]{32}$

    Example: b8e1aeda078009cf3db74e90d5d42328

  • curl -X DELETE -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/queue_managers/<queue_manager_id>'

Response

A URI for status that can be queried periodically to get the status of the queue manager.

Status Code

  • Returns url to track progress for delete queue manager.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "queue_manager_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers",
      "queue_manager_status_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/status",
      "queue_manager_id": "b8e1aeda078009cf3db74e90d5d42328"
    }

Upgrade a queue manager

Upgrade a queue manager.

PUT /v1/{service_instance_guid}/queue_managers/{queue_manager_id}/version

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • The id of the queue manager to retrieve its full details.

    Possible values: length = 32, Value must match regular expression ^[0-9a-fA-F]{32}$

    Example: b8e1aeda078009cf3db74e90d5d42328

Version to upgrade Queue Manager to.

Examples:
View
  • curl -X PUT -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{
      "version": "9.3.2_2"
    }' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/queue_managers/<queue_manager_id>/version'

Response

A URI for status that can be queried periodically to get the status of the queue manager.

Status Code

  • Returns url to track progress of the queue manager upgrade.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Method not allowed

  • Conflict

  • Service Is Overused

  • Internal Server Error

  • Service Unavailable Error

Example responses
  • {
      "queue_manager_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers",
      "queue_manager_status_uri": "/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/queue_managers/b8e1aeda078009cf3db74e90d5d42328/status",
      "queue_manager_id": "b8e1aeda078009cf3db74e90d5d42328"
    }

Get the list of available versions that this queue manager can be upgraded to

Get the list of available versions that this queue manager can be upgraded to.

GET /v1/{service_instance_guid}/queue_managers/{queue_manager_id}/available_versions

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • The id of the queue manager to retrieve its full details.

    Possible values: length = 32, Value must match regular expression ^[0-9a-fA-F]{32}$

    Example: b8e1aeda078009cf3db74e90d5d42328

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/queue_managers/<queue_manager_id>/available_versions'      

Response

The list of available versions that this queue manger can upgrade to.

Status Code

  • Returns information about the available versions that this queue manager can be upgraded to.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "total_count": 1,
      "versions": [
        {
          "version": "9.3.2_2",
          "target_date": "2023-01-13T15:39:35.000Z"
        }
      ]
    }

Get connection information for a queue manager

Get connection information for a queue manager.

GET /v1/{service_instance_guid}/queue_managers/{queue_manager_id}/connection_info

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • The id of the queue manager to retrieve its full details.

    Possible values: length = 32, Value must match regular expression ^[0-9a-fA-F]{32}$

    Example: b8e1aeda078009cf3db74e90d5d42328

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/queue_managers/<queue_manager_id>/connection_info'

Response

Responds with JSON CCDT of the connection information for the queue manager.

Status Code

  • Response of the connection information for the queue manager.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "channel": [
        {
          "name": "CLOUD.ADMIN.SVRCONN",
          "clientConnection": {
            "connection": [
              {
                "host": "myqm-fre.qm1.eu-de.mq2.cloud.ibm.com",
                "port": 30446
              }
            ],
            "queueManager": "myqm"
          },
          "transmissionSecurity": {
            "cipherSpecification": "ANY_TLS12_OR_HIGHER"
          },
          "type": "clientConnection"
        }
      ]
    }

Get the status of the queue manager

Get the status of the queue manager instance.

GET /v1/{service_instance_guid}/queue_managers/{queue_manager_id}/status

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • The id of the queue manager to retrieve its full details.

    Possible values: length = 32, Value must match regular expression ^[0-9a-fA-F]{32}$

    Example: b8e1aeda078009cf3db74e90d5d42328

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/queue_managers/<queue_manager_id>/status'

Response

Queue manager status.

Status Code

  • Current status for the queue manager.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "status": "running"
    }

Get a list of users for an instance

Get a list of users for an instance.

GET /v1/{service_instance_guid}/users

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

Query Parameters

  • Pagination offset.

    Possible values: 0 ≤ value ≤ 99999

    Default: 0

  • The numbers of resources to return.

    Possible values: 0 ≤ value ≤ 100

    Default: 25

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/users'

Response

A list of user summaries.

Status Code

  • Summary of the returned users.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "offset": 25,
      "limit": 25,
      "first": {
        "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/users?limit=25"
      },
      "next": {
        "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/users?offset=50&limit=25"
      },
      "previous": {
        "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/users?offset=25&limit=25"
      },
      "users": [
        {
          "id": "31a413dd84346effc8895b6ba4641641",
          "name": "t0scie98o57a",
          "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/users/31a413dd84346effc8895b6ba4641641",
          "email": "user@example.com"
        }
      ]
    }

Add a user to an instance

Add a user to an instance.

POST /v1/{service_instance_guid}/users

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

User to add to the list.

  • curl -X POST -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{
      "name": "testuser",
      "email": "testuser@ibm.com"
    }' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/users'

Response

A summary of the user for use in a list of users.

Status Code

  • Created User

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Conflict

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "id": "31a413dd84346effc8895b6ba4641641",
      "name": "t0scie98o57a",
      "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/users/31a413dd84346effc8895b6ba4641641",
      "email": "user@example.com"
    }

Get a user for an instance

Get a user for an instance.

GET /v1/{service_instance_guid}/users/{user_id}

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • The id of the user.

    Possible values: length = 32, Value must match regular expression ^[0-9a-fA-F]{32}$

    Example: 31a413dd84346effc8895b6ba4641641

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/users/<user_id>'

Response

A summary of the user for use in a list of users.

Status Code

  • Description of the returned user.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

Example responses
  • {
      "id": "31a413dd84346effc8895b6ba4641641",
      "name": "t0scie98o57a",
      "href": "https://api.private.eu-de.mq2.cloud.ibm.com/v1/a2b4d4bc-dadb-4637-bcec-9b7d1e723af8/users/31a413dd84346effc8895b6ba4641641",
      "email": "user@example.com"
    }

Delete a user for an instance

Delete a user for an instance.

DELETE /v1/{service_instance_guid}/users/{user_id}

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

  • The id of the user.

    Possible values: length = 32, Value must match regular expression ^[0-9a-fA-F]{32}$

    Example: 31a413dd84346effc8895b6ba4641641

  • curl -X DELETE -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/users/<user_id>'

Response

Status Code

  • Resource was deleted successfully.

  • URI has permanently Moved

  • Bad Request

  • Unauthorized

  • Resource not found

  • Service Is Overused

  • Internal Server Error

No Sample Response

This method does not specify any sample responses.

Get a list of applications for an instance

Get a list of applications for an instance.

GET /v1/{service_instance_guid}/applications

Request

Custom Headers

  • The acceptable list of languages supported in the client.

    Possible values: 1 ≤ length ≤ 256, Value must match regular expression [a-zA-Z0-9\-]*

Path Parameters

  • The GUID that uniquely identifies the MQ on Cloud service instance.

    Possible values: length = 36, Value must match regular expression ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

    Example: a2b4d4bc-dadb-4637-bcec-9b7d1e723af8

Query Parameters

  • Pagination offset.

    Possible values: 0 ≤ value ≤ 99999

    Default: 0

  • The numbers of resources to return.

    Possible values: 0 ≤ value ≤ 100

    Default: 25

  • curl -X GET -H 'Authorization: Bearer <iam_access_token>' -H 'Accept: application/json' 'https://api.private.<region>.mq2.cloud.ibm.com/v1/<service_instance_guid>/applications'

Response

A list of application summaries.