canonical: https://jentic.com/apis/ibm.com/ibm-mq-rest-api

# IBM MQ REST API

IBM MQ is the enterprise message-oriented middleware that backs many bank, insurance, and supply-chain integrations, and the IBM MQ REST API exposes administration and messaging operations over HTTPS so that systems without a native MQ client can still participate. The spec covers queue manager, queue, channel, and subscription administration, plus a messaging endpoint for putting and getting messages on a named queue. It is suited to teams that need to drive MQ from cloud-native services, browsers, or AI agents that cannot bundle the MQ client libraries.

## For AI agents

Administer IBM MQ queue managers, queues, channels, and subscriptions, and put or get messages on a queue over HTTPS - without an MQ client.

## Scope

Does not handle queue manager provisioning, MQ client library configuration, or MQTT pub/sub - use for MQ administration and HTTPS-based queue messaging only.

## Capabilities

- Administer queue managers via `/v2/admin/qmgr` and `/v2/admin/qmgr/{qmgrName}`
- Manage queues on a queue manager via `/v2/admin/qmgr/{qmgrName}/queue`
- Configure channels and subscriptions via `/v2/admin/qmgr/{qmgrName}/channel` and /subscription
- Put or get messages on a named queue via `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message`
- Authenticate REST sessions via `/v1/login` and `/v1/logout`

## Use cases

### Cloud-Native MQ Producer

Send messages onto an IBM MQ queue from a service that cannot run the MQ client libraries - a serverless function, a browser, or an AI agent - by POSTing to `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message.` This makes it possible to bridge cloud-native systems into a bank or insurer's existing MQ-based messaging backbone without distributing native binaries.

Example prompt: POST a JSON message body to `/v2/messaging/qmgr/QM1/queue/ORDERS.IN/message` with content type application/json and the order payload.

### Queue Administration

Inspect and configure queues, channels, and subscriptions on a queue manager from an external automation tool. The API exposes admin endpoints under `/v2/admin/qmgr/{qmgrName}`/* so an operator or agent can list queues, create new ones, and audit channel configuration without using the MQ Explorer UI.

Example prompt: GET `/v2/admin/qmgr/QM1/queue` and return the list of queues whose name starts with PAYMENTS.

### Cross-System Bridging

Use the REST messaging endpoint as a bridge between MQ and HTTP-only systems - for example, drop messages onto MQ when a webhook fires, or read MQ messages and forward them to a Slack channel. Because the API speaks HTTPS, it integrates cleanly into iPaaS tools and Jentic-driven agents.

Example prompt: GET a single message from `/v2/messaging/qmgr/QM1/queue/ALERTS/message` and post the message body to a configured Slack channel.

### AI Agent Messaging Operator

An AI agent uses Jentic to enqueue messages on MQ as part of a larger workflow - for example, submitting a payment instruction onto a banking system's intake queue. The agent searches by intent, loads the messaging schema, and executes the call, never holding the raw MQ credentials. Typical agent integration is under one hour because the messaging surface is small and well-scoped.

Example prompt: Search Jentic for 'put a message on an IBM MQ queue', load the `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message` schema, and submit the payment instruction.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v2/admin/qmgr` | List queue managers |
| GET | `/v2/admin/qmgr/{qmgrName}/queue` | List queues on a queue manager |
| GET | `/v2/admin/qmgr/{qmgrName}/channel` | List channels on a queue manager |
| POST | `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message` | Put a message on a queue |
| DELETE | `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message` | Get and remove the next message |
| POST | `/v1/login` | Establish a REST session |
| POST | `/v1/logout` | End a REST session |

## Key resources

- **Queue Managers** — List and configure queue managers
- **Queues** — Create, list, and inspect queues
- **Channels** — Inspect and configure MQ channels
- **Subscriptions** — Manage topic subscriptions
- **Messaging** — Put and get messages over HTTPS
- **Authentication** — Log in and out of REST sessions

## Why Jentic

- **Setup:** Wiring the IBM MQ REST API by hand means picking among its apiKey, basic, and token auth options, targeting your queue manager host and port, and mapping its admin and messaging routes yourself. Through Jentic you install once, import the IBM MQ REST API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** MQ REST puts the queue manager and queue names in the URL path (`/qmgr/{qmgrName}/queue/{queueName}`), so a rule can pin your agent to one queue manager: it can read admin state and post messages there and nowhere else. You choose the operations it may call, so deleting messages from a queue is not included unless you add it.
- **Credential handling:** Your MQ credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'put a message on an MQ queue' or 'list a queue manager's queues', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **IBM MQ Cloud API** — MQ Cloud provisions and manages cloud-hosted queue managers; the MQ REST API operates on the queue manager once it exists.
- **Azure Service Bus Management API** — Azure Service Bus is a cloud-native enterprise messaging service; IBM MQ is the on-premises and IBM Cloud equivalent.
- **Confluent Kafka API** — Confluent Kafka is a streaming platform with topic-based pub/sub; IBM MQ is a queue-based enterprise messaging system.

## FAQ

### What authentication does the IBM MQ REST API use?

The MQ REST API supports three schemes: an LtpaToken2 cookie set by `/v1/login`, HTTP basic authentication, and HTTP bearer authentication. Through Jentic, the chosen credentials are stored in your Jentic One instance and the agent calls MQ via a scoped Jentic credential.

### Can I put a message on an IBM MQ queue with this API?

Yes. POST the message payload to `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message.` The endpoint accepts both text and JSON payloads and writes them onto the named queue without requiring a native MQ client.

### How do I get the next message off a queue?

DELETE `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message` returns and removes the next available message from the queue. The destructive read pattern matches the MQ get-with-remove semantics used by traditional MQ clients.

### How do I send a message to IBM MQ through Jentic?

Search Jentic for 'put a message on an IBM MQ queue', load the `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message` schema, and execute. Install the SDK with pip install jentic and use the async search, load, execute pattern from Python.

### Can I administer queue managers and queues over the REST API?

Yes. The `/v2/admin/qmgr` endpoints cover queue manager listing and inspection, `/v2/admin/qmgr/{qmgrName}/queue` covers queue administration, and `/v2/admin/qmgr/{qmgrName}/channel` and /subscription cover channels and topic subscriptions.

### What are the rate limits for the IBM MQ REST API?

IBM MQ does not enforce a fixed REST rate limit; throughput depends on the queue manager configuration, channel limits, and the deployment topology. Treat HTTP 429 and 503 as backpressure and retry with exponential backoff.

### Can I limit what my agent is allowed to do with the IBM MQ REST API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. Since the IBM MQ REST API puts the queue manager and queue names in the URL path, such as `/v2/messaging/qmgr/{qmgrName}/queue/{queueName}/message`, you can pin the agent to a single queue manager and let it read admin state and put messages there and nowhere else. Because you choose the exact operations it may call, a destructive read like DELETE on a queue message is excluded unless you add it.