Skip to main content
Version: Next

HTTP API Reference

Introduction​

This is a reference page for the RabbitMQ HTTP API.

Client Libraries for the HTTP API​

There are several mature HTTP API client libraries available, see Developer Tools.

HTTP API-based CLI Tool​

In addition to client libraries, there is an HTTP API-specific CLI tool for both interactive and script use.

See rabbitmqadmin v2, a Command Line Tool for the HTTP API to learn more.

Overview​

All HTTP API API endpoints will serve only resources of type application/json, and will require HTTP basic authentication (using the standard RabbitMQ user database). The default user is guest/guest.

Many URIs require the name of a virtual host as part of the path, since names only uniquely identify objects within a virtual host. As the default virtual host is called "/", this will need to be encoded as "%2F".

PUTing a resource creates it. The JSON object you upload must have certain mandatory keys (documented below) and may have optional keys. Other keys are ignored. Missing mandatory keys constitute an error.

Since bindings do not have names or IDs in AMQP we synthesise one based on all its properties. Since predicting this name is hard in the general case, you can also create bindings by POSTing to a factory URI. See the example below.

Many URIs return lists. Such URIs can have the query string parameters sort and sort_reverse added. sort allows you to select a primary field to sort by, and sort_reverse will reverse the sort order if set to true. The sort parameter can contain subfields separated by dots. This allows you to sort by a nested component of the listed items; it does not allow you to sort by more than one field. See the example below.

You can also restrict what information is returned per item with the columns parameter. This is a comma-separated list of subfields separated by dots. See the example below.

It is possible to disable the statistics in the GET requests and obtain just the basic information of every object. This reduces considerably the amount of data returned and the memory and resource consumption of each query in the system. For some monitoring and operation purposes, these queries are more appropriate.

To opt out of the additional metrics, set the disable_stats query parameter to true

Endpoint Reference​

tip

The examples below use rabbitmqadmin v2 or curl.

However, the API can be used with any HTTP client. Team RabbitMQ strongly recommends a number of dedicated HTTP API client libraries.

tip

The examples that produce JSON output also format the output with jq. The use of jq is entirely optional.

GET /api/overview​

Various random bits of information that describe the whole system.

Examples​

# jq is used for pretty-printing the result. It is entirely optional.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/overview | jq

GET /api/cluster-name​

Returns the name identifying this RabbitMQ cluster.

Examples​

# jq is used for pretty-printing the result. It is entirely optional.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/cluster-name | jq

PUT /api/cluster-name​

Updates the name identifying this RabbitMQ cluster.

GET /api/nodes​

Lists all nodes in the cluster together with their metrics.

Examples​

# jq is used for pretty-printing the result. It is entirely optional.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/nodes | jq

GET /api/nodes/{name}​

Returns metrics of an individual cluster node.

Examples​

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/nodes/rabbit@hostname | jq

GET /api/nodes/{name}/memory​

Returns a memory usage breakdown of a specific cluster node.

Examples​

# jq is used for pretty-printing the result. It is entirely optional.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/nodes/rabbit@hostname/memory | jq

GET /api/definitions​

Exports cluster-wide definitions: all exchanges, queues, bindings, users, virtual hosts, permissions, topic permissions, and parameters. That is, everything apart from messages.

Examples​

# jq is used for pretty-printing the result. It is entirely optional.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/definitions | jq

Relevant documentation guide: Definition Export and Import.

POST /api/definitions​

The server definitions: exchanges, queues, bindings, users, virtual hosts, permissions, topic permissions, and parameters. Everything apart from messages. POST to upload an existing set of definitions. Note that:

  • Cluster-wide definitions use a different format from the virtual host-specific ones. Virtual host-specific definitions cannot be imported using this endpoint. Use the POST /api/definitions/{vhost} endpoint instead.

  • The definitions are merged. Anything already existing on the server but not in the uploaded definitions is untouched.

  • Conflicting definitions on immutable objects (exchanges, queues and bindings) will be ignored. The existing definition will be preserved.

  • Conflicting definitions on mutable objects will cause the object in the server to be overwritten with the object from the definitions.

  • In the event of an error you will be left with a partially-applied set of definitions.

This endpoint supports multipart/form-data as well as the standard application/json content types for uploads. In the former case, the definitions file should be uploaded as a form field named "file".

Relevant documentation guide: Definition Export and Import.

GET /api/definitions/{vhost}​

Exports definitions of a single virtual host.

Virtual host-specific definitions do not contain any details on the virtual host name, and can be imported into any virtual host. That is, the original name of the virtual host does not have to match the name of the target virtual host when the definitions are imported.

Relevant documentation guide: Definition Export and Import.

Examples​

# jq is used for pretty-printing the result. It is entirely optional.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/definitions/%2F | jq

POST /api/definitions/{vhost}​

Imports (uploads) definitions from a single virtual host: exchanges, queues, bindings, users, permissions in that virtual host, topic permissions, and parameters.

Note that:

  • Cluster-wide definitions cannot be imported using this endpoint. Use the POST /api/definitions/ endpoint instead.

  • Virtual host-specific definitions do not contain any details on the virtual host name, and can be imported into any virtual host. That is, the original name of the virtual host does not have to match the name of the target virtual host when the definitions are imported.

  • The definitions are merged. Anything already existing on the server but not in the uploaded definitions is untouched.

  • Conflicting definitions on immutable objects (exchanges, queues and bindings) will be ignored. The existing definition will be preserved.

  • Conflicting definitions on mutable objects will cause the object in the server to be overwritten with the object from the definitions.

  • In the event of an error you will be left with a partially-applied set of definitions.

This endpoint supports multipart/form-data as well as the standard application/json content types for uploads. In the former case, the definitions file should be uploaded as a form field named "file".

Relevant documentation guide: Definition Export and Import.

GET /api/feature-flags​

Lists all feature flags and their state.

Relevant documentation guide: Feature Flags.

Examples​

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/feature-flags | jq

GET /api/deprecated-features​

Lists all deprecated features and their state.

Relevant documentation guide: Deprecated Features

Examples​

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/feature-flags | jq

GET /api/deprecated-features/used​

Lists the deprecated features that are used in this cluster.

Relevant documentation guide: Deprecated Features

Examples​

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/deprecated_features/used | jq

GET /api/connections​

A list of all open connections.

Use pagination parameters to list connections, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

# This request can result in a very large JSON document
# and unnecessarily wasted CPU resources.
#
# Never use it to fetch information about a single connection.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/connections | jq

GET /api/vhosts/{vhost}/connections​

A list of all open connections in a specific virtual host.

Use pagination parameters to list connections, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

GET /api/connections/{name}​

Returns metrics of an individual connection.

# the connection name must be percent-encoded
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/connections/127.0.0.1%3A54594%20-%3E%20127.0.0.1%3A5672 | jq

DELETE /api/connections/{name}​

Closes the connection. Optionally set the "X-Reason" header to provide a reason.

# the connection name must be percent-encoded
curl -sL -u guest:guest -X DELETE -H "Accept: application/json" http://127.0.0.1:15672/api/connections/127.0.0.1%3A62965%20-%3E%20127.0.0.1%3A5672

GET /api/connections/username/{username}​

A list of all open connections that authenticated using a specific username.

# the connection name must be percent-encoded
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/connections/username/guest

DELETE /api/connections/username/{username}​

Close all the connections of a user.

Optionally set the "X-Reason" header to provide a reason.

# the connection name must be percent-encoded
curl -sL -u guest:guest -X DELETE -H "Accept: application/json" http://127.0.0.1:15672/api/connections/127.0.0.1%3A62965%20-%3E%20127.0.0.1%3A5672

GET /api/connections/{name}/channels​

List of all channels for a given connection.

Use pagination parameters to list channels, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

# the connection name must be percent-encoded
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/connections/127.0.0.1%3A52066%20-%3E%20127.0.0.1%3A5672/channels | jq

GET /api/channels​

A list of all open channels.

Use pagination parameters to list channels, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

# This request can result in a very large JSON document
# and unnecessarily wasted CPU resources.
#
# Never use it to fetch information about a single channel.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/channels

GET /api/vhosts/{vhost}/channels​

A list of all open channels in a specific virtual host.

Use pagination parameters to list channels, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

GET /api/channels/{id}​

Details about an individual channel.

GET /api/consumers​

A list of all consumers.

Use pagination parameters to list consumers, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

# This request can result in a very large JSON document
# and unnecessarily wasted CPU resources.
#
# Never use it to fetch information about a single consumers.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/consumers

GET /api/consumers/{vhost}​

A list of all consumers in a given virtual host.

GET /api/exchanges​

A list of all exchanges. Use pagination parameters to list exchanges.

# This request can result in a very large JSON document
# and unnecessarily wasted CPU resources.
#
# Never use it to fetch information about a single exchange.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/exchanges

GET /api/exchanges/{name}​

A list of all exchanges in a given virtual host. Use pagination parameters to list exchanges.

GET /api/exchanges/{vhost}/{name}​

Returns metrics of an individual exchange.

PUT /api/exchanges/{vhost}/{name}​

Declares an exchange.

Payload example:

{
  "type": "direct",
  "auto_delete": false,
  "durable": true,
  "internal": false,
  "arguments": {}
}

DELETE /api/exchanges/{vhost}/{name}​

Deletes an exchange. Set the if-unused query parameter to true to make the operaion a no-op if the exchange is bound to a queue or as a source to another exchange

GET /api/exchanges/{vhost}/{name}/bindings/source​

A list of all bindings in which a given exchange is the source.

GET /api/exchanges/{vhost}/{name}/bindings/destination​

A list of all bindings in which a given exchange is the destination.

PUT /api/exchanges/{vhost}/{name}/publish​

Publish a message to a given exchange. A payload example:

{
  "properties": {},
  "routing_key": "my key",
  "payload": "my body",
  "payload_encoding": "string"
}

All keys are mandatory.

The payload_encoding key should be either "string" (in which case the payload will be taken to be the UTF-8 encoding of the payload field) or "base64" (in which case the payload field is taken to be base64 encoded).

If the message is published successfully, the response will look like:

{"routed": true}

routed will be true if the message was sent to at least one queue.

danger

Note that the HTTP API is a highly inefficient option for publishing;

Prefer AMQP 1.0, AMQP 0-9-1, the RabbitMQ Streaming Protocol or any other messaging protocol supported by RabbitMQ.

GET /api/queues​

A list of all queues across all virtual hosts returning a reduced set of fields.

Use pagination parameters to list queues, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

The parameter enable_queue_totals=true can be used in combination with the disable_stats=true parameter to return a reduced set of fields and significantly reduce the amount of data returned by this endpoint. That in turn can significantly reduce CPU and bandwidth footprint of such requests.

# This request can result in a very large JSON document
# and unnecessarily wasted CPU resources.
#
# Never use it to fetch information about a single queue.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/queues

GET /api/queues/detailed​

A list of all queues containing all available information about the queues (over 50 fields per queue).

Use pagination parameters to list queues, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

GET /api/queues/{vhost}​

A list of all queues in the given virtual host containing all available information about the queues (over 50 fields per queue)..

Use pagination parameters to list queues, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

# This request can result in a very large JSON document
# and unnecessarily wasted CPU resources.
#
# Never use it to fetch information about a single queue.
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/queues/%2F

GET /api/queues/{vhost}/{name}​

Returns metrics of a queue.

PUT /api/queues/{vhost}/{name}​

Declares a queue.

Example payload:

{
  "auto_delete": false,
  "durable": true,
  "arguments": {},
  "node": "rabbit@node.hostname"
}

DELETE /api/queues/{vhost}/{name}​

Deletes a queue.

Two query string parameters, if-empty=true and/or if-unused=true, can be used for conditional deletion.

GET /api/queues/{vhost}/{name}/bindings​

A list of all bindings on a given queue.

DELETE /api/queues/{vhost}/{name}/contents​

Purges a queue (deletes all messages in Ready state in it).

POST /api/queues/{vhost}/{name}/get​

Get messages from a queue. (This is not an HTTP GET as it will alter the state of the queue.) You should post a body looking like:

{
  "count": 5,
  "ackmode": "ack_requeue_true",
  "encoding": "auto",
  "truncate": 50000
}

count controls the maximum number of messages that can be returned (fetched) at once.

The ackmode parameter controls how the consumed messages are acknowledged. The supported values are

  • ack_requeue_true
    • : requeues the fetched messages
  • reject_requeue_true
    • : requeues the fetched messages
  • ack_requeue_false
    • : positively acknowledges the messages and marks them for deletion
  • reject_requeue_false
    • : negatively acknowledges the messages and marks them for deletion

The encoding can be either "auto" (the payload will be returned as a UTF-8 encoded string if the payload is valid UTF-8) or "base64" (a Base64-encoded payload).

If the truncate key is set to a value in bytes, messages longer than the value will be truncated.

danger

This endpoint intended for development and troubleshooting only, not for production. In production, use a messaging or streaming protocol client library instead.

GET /api/bindings​

A list of all bindings.

Use pagination parameters to list bindings, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

# This request can result in a very large JSON document
# and unnecessarily wasted CPU resources.
#
# Never use it to fetch information about a single queue.
#
# The virtual host name must be percent-encoded
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/queues/%2F

GET /api/bindings/{vhost}​

Use pagination parameters to list bindings, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

# the virtual host name must be percent-encoded
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/bindings/%2F

GET /api/bindings/{vhost}/e/{exchange}/q/{queue}​

Returns a list of all bindings between an exchange and a queue.

An exchange and a queue can be bound together many times, so this list can contain multiple bindings for the same pair.

POST /api/bindings/{vhost}/e/{exchange}/q/{queue}​

Binds a queue to an exchange.

Request body should be a JSON object optionally containing two fields, routing_key (a string) and arguments (a map of optional arguments):

{
  "routing_key": "my_routing_key",
  "arguments": {"x-optional-arg": "optional-value"}
}

Both payload keys are optional.

The response will contain a Location header with a URI of the newly declared binding.

GET /api/bindings/{vhost}/e/{exchange}/q/{queue}/{props}​

Retrieves an individual binding between an exchange and a queue.

The {props} part of the URI is a "name" for the binding composed of its routing key and a hash of its arguments.

{props} is the field named properties_key from a bindings listing response.

DELETE /api/bindings/{vhost}/e/{exchange}/q/{queue}/{props}​

Deletes an individual binding between an exchange and a queue.

The {props} part of the URI is a "name" for the binding composed of its routing key and a hash of its arguments.

{props} is the field named properties_key from a bindings listing response.

GET /api/bindings/{vhost}/e/{source}/e/{destination}​

POST /api/bindings/{vhost}/e/{source}/e/{destination}​

Creates a new exchange-to-exchange binding.

Request body should be a JSON object optionally containing two fields, routing_key (a string) and arguments (a map of optional arguments):

{
  "routing_key": "my_routing_key",
  "arguments": {
    "x-arg": "value"
  }
}

Both of the keys are optional.

The response will contain a Location header with a URI of the newly declared binding.

GET /api/bindings/{vhost}/e/{source}/e/{destination}/{props}​

Returns the details of a specific exchange-to-exchange binding.

DELETE /api/bindings/{vhost}/e/{source}/e/{destination}/{props}​

Deletes an exchange-to-exchange binding.

GET /api/vhosts​

Returns a list of all virtual hosts in the cluster.

Pagination: default page size is 100, maximum supported page size is 500.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/vhosts

GET /api/vhosts/{name}​

Returns metrics of a specific virtual host.

PUT /api/vhosts/{name}​

Creates a virtual host or updates the metadata of an existing virtual host.

Payload example:

{
  "description": "virtual host description",
  "tags": "accounts,production",
  "default_queue_type": "quorum",
  "protected_from_deletion": false
}

The tags key must be a comma-separated list of tags. These metadata fields are optional.

To enable or disable tracing, use the tracing key:

{"tracing":true}

DELETE /api/vhosts/{name}​

Deletes a virtual host, as long as it is not deletion-protected.

GET /api/vhosts/{name}/permissions​

A list of all permissions for a given virtual host.

GET /api/vhosts/{name}/topic-permissions​

A list of all topic permissions for a given virtual host.

POST /api/vhosts/{name}/deletion/protection​

Protects a virtual host from deletion. Virtual hosts marked as protected cannot be deleted until the protection is lifted.

DELETE /api/vhosts/{name}/deletion/protection​

Removes deletion protection from a virtual host so that it can be deleted.

POST /api/vhosts/{name}/start/{node}​

Starts or restarts a virtual host on the node.

Doing this explicitly is almost never necessary. RabbitMQ nodes ensure that all virtual hosts have been started on all cluster nodes for the first few minutes after cluster formation (more specifically after each cluster member's startup time).

GET /api/users​

Lists all users in the cluster. This only includes the users in the internal data store. For example, if the LDAP backend is used, this command will not include any LDAP users.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/users

GET /api/users/without-permissions​

Lists the users that do not have any permissions (cannot access any virtual hosts) and could be safely deleted.

POST /api/users/bulk-delete​

Bulk deletes a list of users. The payload must include the users key that is an array of usernames:

{"users" : ["user1", "user2", "user3"]}

GET /api/users/{name}​

Returns information about a user in the internal data store.

PUT /api/users/{name}​

Creates a user. A password or a password hash must be provided in the payload:

{"password":"secret","tags":"administrator"}
{"password_hash":"2lmoth8l4H0DViLaK9Fxi6l9ds8=", "tags":["administrator"]}

password_hash must be generated using the algorithm described in the Passwords guide.

The tags key takes a comma-separated list of tags.

If neither are set the user will not be able to log in with a password, but other mechanisms like client certificates may be used.

Setting password_hash to an empty string ("") will ensure the user cannot use a password to log in.

The hash function can be overriden using the hashing_algorithm key. Currently recognised algorithms are rabbit_password_hashing_sha256, rabbit_password_hashing_sha512, and rabbit_password_hashing_md5.

DELETE /api/users/{name}​

Deletes a user.

GET /api/users/{user}/permissions​

A list of all permissions for a given user.

GET /api/users/{user}/topic-permissions​

A list of all topic permissions for a given user.

GET /api/user-limits​

Lists per-user limits for all users.

GET /api/user-limits/{user}​

Lists per-user limits for a specific user.

PUT /api/user-limits/{user}/{name}​

Set or delete per-user limit for user. The name URL path element refers to the name of the limit (max-connections, max-channels).

Limits are set using a JSON document in the body:

{"value": 100}

An example request using curl:

curl -4u 'guest:guest' -H 'content-type:application/json' -X PUT localhost:15672/api/user-limits/guest/max-connections -d '{"value": 100}'

DELETE /api/user-limits/{user}/{name}​

Clears a per-user limit.

GET /api/permissions​

A list of all user permissions in the cluster.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/permissions

GET /api/permissions/{vhost}/{user}​

Returns a user's permissions in the given virtual host.

PUT /api/permissions/{vhost}/{user}​

Grants (creates) or updates user permissions in the given virtual host.

Payload example

{"configure":".*","write":".*","read":".*"}

All three permissions must be explicitly provided.

DELETE /api/permissions/{vhost}/{user}​

Revokes user permissions in the given virtual host.

GET /api/topic-permissions​

Lists all topic exchange permissions in the cluster.

GET /api/topic-permissions/{vhost}/{user}​

Returns a user's topic exchange permissions in the given virtual host.

PUT /api/topic-permissions/{vhost}/{user}​

Grants or updates a user's topic exchange permission of a user.

{
  "exchange": "amq.topic",
  "write": "^a",
  "read":".*",
  "configure":".*"
}

All the keys from the example above are mandatory.

DELETE /api/topic-permissions/{vhost}/{user}​

Revokes topic exchange permissions of a user.

GET /api/parameters​

Returns a list of runtime parameters across all virtual hosts in the cluster.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/parameters

GET /api/parameters/{component}​

GET /api/parameters/{component}/{vhost}​

GET /api/parameters/{component}/{vhost}/{name}​

PUT /api/parameters/{component}/{vhost}/{name}​

Creates or updates a runtime parameter.

Example body:

{
  "vhost": "vh-2",
  "name": "policies.1",
  "pattern": "^cq",
  "apply-to": "queues",
  "definition": {
    "max-length": 1000000
  }
}

DELETE /api/parameters/{component}/{vhost}/{name}​

Deletes a runtime parameter.

GET /api/global-parameters​

Lists all global runtime parameters in the cluster.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/global-parameters

GET /api/global-parameters/{name}​

Returns the value (definition) of the given global runtime parameter.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/global-parameters/cluster_name

PUT /api/global-parameters/{name}​

Sets the given global runtime parameter.

Example payloads:

{
  "name": "cluster_name",
  "value": "prod-456"
}
{
  "name": "cluster_tags",
  "value": {
    "environment": "production",
    "az": "ca-central-1"
  }
}
curl -sL -u guest:guest -X PUT -H "Accept: application/json" -H "Content-Type: application/json" http://127.0.0.1:15672/api/global-parameters/cluster_tags \
     --data '{"value": {"region": "ca-central-1", "environment": "production"}, "name": "cluster_tags"}'

DELETE /api/global-parameters/{name}​

Clears a global runtime parameter.

curl -sL -u guest:guest -X DELETE -H "Accept: application/json" http://127.0.0.1:15672/api/global-parameters/cluster_tags

GET /api/policies​

Lists policies across all virtual hosts in the cluster.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/policies

GET /api/policies/{vhost}​

Lists policies in the given virtual host.

# The virtual host name must be percent-encoded
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/policies/%2F

GET /api/policies/{vhost}/{name}​

Returns a policy definition.

PUT /api/policies/{vhost}/{name}​

Declares or updates a policy.

Example payload:

{"pattern":"^amq.", "definition": {"federation-upstream-set":"all"}, "priority": 10, "apply-to": "queues"}

All the keys in the example are mandatory.

important

Only one policy applies or a queue, stream or exchange at a time.

When multiple policies have conflicting priorities, a random one will be applied. This scenario therefore must be avoided.

DELETE /api/policies/{vhost}/{name}​

Deletes a policy.

GET /api/operator-policies​

Lists operator policies across all virtual hosts in the cluster.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/operator-policies

GET /api/operator-policies/{vhost}​

Returns an operator policy definition.

# The virtual host name must be percent-encoded
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/operator-policies/%2F

GET /api/operator-policies/{vhost}/{name}​

Returns an operator policy definition.

PUT /api/operator-policies/{vhost}/{name}​

Example payload:

{"pattern":"^amq.", "definition": {"federation-upstream-set":"all"}, "priority": 10, "apply-to": "queues"}

All the keys in the example are mandatory.

important

Only one policy applies or a queue, stream or exchange at a time.

When multiple policies have conflicting priorities, a random one will be applied. This scenario therefore must be avoided.

DELETE /api/operator-policies/{vhost}/{name}​

Deletes an operator policy.

GET /api/vhost-limits​

Lists all virtual host limits configured across the cluster.

curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/vhost-limits

GET /api/vhost-limits/{vhost}​

Lists virtual host limits configured for the target virtual host.

# The virtual host name must be percent-encoded
curl -sL -u guest:guest -H "Accept: application/json" http://127.0.0.1:15672/api/vhost-limits/%2F

PUT /api/vhost-limits/{vhost}/{name}​

Set or delete per-vhost limit for vhost. The name URL path element refers to the name of the limit (max-connections, max-queues).

Limits are set using a JSON document in the body:

{"value": 100}

Example request:

curl -4u 'guest:guest' -H 'content-type:application/json' -X PUT localhost:15672/api/vhost-limits/my-vhost/max-connections -d '{"value": 50}'

Relevant documentation guide: Virtual Hosts.

DELETE /api/vhost-limits/{vhost}/{name}​

Clears (removes) a virtual host limit.

Provides status for all federation links across all virtual hosts in the cluster.

This endpoint will only be available the rabbitmq_federation_management plugin is enabled.

Relevant documentation guide: Federation.

GET /api/federation-links/{vhost}​

Provides status for all federation links in the given virtual host.

This endpoint will only be available the rabbitmq_federation_management plugin is enabled.

Relevant documentation guide: Federation.

GET /api/auth/attempts/{node}​

A list of client authentication attempts registered by the node.

GET /api/auth/attempts/{node}/source​

A list of client authentication attempts grouped by remote address and username.

GET /api/auth/hash_password/{password}​

Hashes the provided password according to the currently configured password hashing algorithm.

GET /api/stream/connections​

Lists all stream protocol connections across all virtual hosts in the cluster.

Use pagination parameters to list connections, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/connections/{vhost}​

A list of all open stream protocol connections in a specific virtual host.

Use pagination parameters to list connections, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/connections/{vhost}/{name}​

Returns metrics of a specific stream protocol connection.

Requires the rabbitmq_stream_management plugin to be enabled.

DELETE /api/stream/connections/{vhost}/{name}​

Closes a specific stream protocol connection.

Optionally set the "X-Reason" header to provide a reason.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/connections/{vhost}/{name}/publishers​

Lists known publishers on a stream protocol connection.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/connections/{vhost}/{name}/consumers​

Lists known consumers on a stream protocol connection.

Use pagination parameters to list consumers, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/publishers​

The list of known publishers across all stream protocol connections.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/publishers/{vhost}​

The list of known publishers for all stream protocol connections in the given virtual host.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/publishers/{vhost}/{stream}​

The list of known publishers to the given stream across all stream protocol connections.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/consumers​

Use pagination parameters to list consumers, otherwise this endpoint can produce very large JSON responses and waste a lot of bandwidth and CPU resources. Default page size is 100, maximum supported page size is 500.

Requires the rabbitmq_stream_management plugin to be enabled.

GET /api/stream/consumers/{vhost}​

The list of stream consumers in a specific virtual host.

Requires the rabbitmq_stream_management plugin to be enabled.

Health Check Endpoints​

GET /api/health/checks/alarms​

Responds a 200 OK if there are no alarms in effect in the cluster, otherwise responds with a 503 Service Unavailable.

Relevant documentation guide: Resource Alarms.

GET /api/health/checks/local-alarms​

Responds a 200 OK if there are no alarms in effect in the cluster, otherwise responds with a 503 Service Unavailable.

Relevant documentation guide: Resource Alarms.

GET /api/health/checks/certificate-expiration/{within}/{unit}​

Checks the expiration date of every certificate found in the PEM certificate bundles used by all TLS-enabled listeners on the node, regardless of the "type" of the certificate (leaf/server identity, intermediary or any CA).

Responds a 200 OK if all certificates are valid (have not expired), otherwise responds with a 503 Service Unavailable.

This health assumes that

  • All certificates included in the PEM bundles on the nodes are relevant to RabbitMQ clients, plugins or encrypted inter-node communication
  • Expired certificates is not a normal operating condition and any expired certificate found must be reported with a check failure

Do not use this health check if some of these assumptions are not true.

Valid units: days, weeks, months, years. The value of the {within} argument is the number of units. So, when {within} is 2 and {unit} is "months", the expiration period used by the check will be the next two months.

Relevant documentation guides: TLS, Encrypted Inter-node Communication.

GET /api/health/checks/port-listener/{port}​

Responds a 200 OK if there is an active listener on the given port, otherwise responds with a 503 Service Unavailable.

Relevant documentation guides: Networking.

GET /api/health/checks/protocol-listener/{protocols}​

Responds a 200 OK if if all given protocols have active listeners, otherwise responds with a 503 Service Unavailable. Multiple protocols may be provided by separating the names with commas.

Valid protocol names are: amqp091, amqp10, mqtt, stomp, web-mqtt, web-stomp.

GET /api/health/checks/virtual-hosts​

Responds a 200 OK if all virtual hosts and running on the target node, otherwise responds with a 503 Service Unavailable.

GET /api/health/checks/node-is-quorum-critical​

Checks if there are quorum queues with minimum online quorum (queues that would lose their quorum and availability if the target node is shut down). Responds a 200 OK if there are no such quorum queues, otherwise responds with a 503 Service Unavailable.

Relevant documentation guide: Quorum Queues.

GET /api/health/checks/is-in-service​

Responds a 200 OK if the target node is booted, running, and ready to serve clients, otherwise responds with a 503 Service Unavailable. If the target node is being drained for maintenance then this check returns 503 Service Unavailable.

GET /api/health/checks/below-node-connection-limit​

Responds a 200 OK if the target node has fewer connections to the AMQP and AMQPS ports than the configured maximum, otherwise responds with a 503 Service Unavailable.

GET /api/health/checks/ready-to-serve-clients​

Responds a 200 OK if the target node is ready to serve clients, otherwise responds with a 503 Service Unavailable. This check combines:

  • /api/health/checks/is-in-service
  • /api/health/checks/protocol-listener/amqp or /api/health/checks/protocol-listener/amqps
  • /api/health/checks/below-node-connection-limit

So this check will only return 200 OK if the target node is in service, an AMQP or AMQPS listener is available and the target node has fewer active AMQP and AMQPS connections that its configured limit.

GET /api/rebalance/queues​

Rebalances all queues in all vhosts.

This operation is asynchronous. Inspect RabbitMQ logs for messages regarding the success or failure of the operation.

curl -4u 'guest:guest' -XPOST localhost:15672/api/rebalance/queues/

GET /api/whoami​

Returns the username of the authenticated user.

GET /api/auth​

Details about the OAuth 2 configuration. It will return HTTP status 200 with a body in the following format:

{"oauth_enabled":"boolean", "oauth_client_id":"string", "oauth_provider_url":"string"}

GET /api/extensions​

A list of registered extensions to the management plugin.

Metrics Returned by the HTTP API​

Most of the GET requests you can issue to the HTTP API return JSON objects with a large number of keys. While a few of these keys represent things you set yourself in a PUT request or AMQP command (e.g. queue durability or arguments), most of them represent statistics to do with the object in question. This page attempts to document them.

It should be read in conjunction with the manual page for rabbitmqctl (see your installation if on Unix / Linux, or the RabbitMQ website for the latest version).

Any field which can be returned by a command of the form

rabbitmqctl list_{object}
rabbitmqctl list_{object}

will also be returned in the equivalent part of the HTTP API, so all those keys are not documented here. However, the HTTP API returns additional metrics compared to the standard CLI tools and rabbitmqadmin v2 alike.

_details objects

Many fields represent a count of some kind: queue length, messages acknowledged, bytes received and so on. Such absolute counts returned by the HTTP API will often have a corresponding _details object which offers information on how this count has changed. So for example, from a queue:

"messages": 123619,
"messages_details": {
  "avg": 41206.333333333336,
  "avg_rate": 1030.1583333333333,
  "rate": 24723.8,
  "samples": [
    {
      "sample": 123619,
      "timestamp": 1400680560000
    },
    {
      "sample": 0,
      "timestamp": 1400680500000
    },
    {
      "sample": 0,
      "timestamp": 1400680440000
    }
  ]
}

Here we have a messages count (the total messages in the queue), with some additional data:

avg

The average value for the requested time period (see below).

avg_rate

The average rate for the requested time period.

rate

How much the count has changed per second in the most recent sampling interval.

samples

Snapshots showing how the value has changed over the requested time period.

avg, avg_rate and samples will only appear if you request a specific time period by appending query parameters to the URL. To do this you need to set an age and an increment for the samples you want. The end of the range returned will always correspond to the present.

Different types of data take different query parameters to return samples, as in the following table. You can specify more than one set of parameters if the resource you are requesting can generate more than one type of sample (for example, queues can return message rates and queue lengths).

Messages sent and receivedmsg_rates_age / msg_rates_incr
Bytes sent and receiveddata_rates_age / data_rates_incr
Queue lengthslengths_age / lengths_incr
Node statistics (e.g. file descriptors, disk space free)node_stats_age / node_stats_incr

For example, appending ?lengths_age=3600&lengths_incr=60 will return the last hour's data on queue lengths, with a sample for every minute.

message_stats objects

Many objects (including queues, exchanges and channels) will return counts of messages passing through them. These are included in a message_stats object (which in turn will contain _details objects for each count, as described above).

These can contain:

publish

Count of messages published.

publish_in

Count of messages published "in" to an exchange, i.e. not taking account of routing.

publish_out

Count of messages published "out" of an exchange, i.e. taking account of routing.

confirm

Count of messages confirmed.

deliver

Count of messages delivered in acknowledgement mode to consumers.

deliver_no_ack

Count of messages delivered in no-acknowledgement mode to consumers.

get

Count of messages delivered in acknowledgement mode in response to basic.get.

get_no_ack

Count of messages delivered in no-acknowledgement mode in response to basic.get.

deliver_get

Sum of all four of the above.

redeliver

Count of subset of messages in deliver_get which had the redelivered flag set.

drop_unroutable

Count of messages dropped as unroutable.

return_unroutable

Count of messages returned to the publisher as unroutable.

Only fields for which some activity has taken place will appear.

Detailed message stats objects

In addition, queues, exchanges and channels can return a breakdown of message stats for each of their neighbours (i.e. adjacent objects in the chain: channel -> exchange -> queue -> channel). This will only happen if the rates_mode configuration item has been switched to detailed from its default of basic.

As this possibly constitutes a large quantity of data, it is also only returned when querying a single channel, queue or exchange rather than a list. Note also that the default sample retention policy means that these detailed message stats do not retain historical data for more than a few seconds.

The detailed message stats objects have different names depending on where they are (documented below). Each set of detailed stats consists of a list of objects with two fields, one identifying the partner object and one stats which is a message_stats object as described above.

Here is an example snippet:

"incoming": [
  {
    "stats": {
      "publish": 352593,
      "publish_details": {
        "rate": 100.2
      }
    },
    "exchange": {
      "name": "my-exchange",
      "vhost": "/"
    }
  }
  {
    "stats": {
      "publish": 543784,
      "publish_details": {
        "rate": 54.6
      }
    },
    "exchange": {
      "name": "amq.topic",
      "vhost": "/"
    }
  }
],

This queue is currently receiving messages from two exchanges: 100.2 msg/s from "my-exchange" and 54.6 msg/s from "amq.topic".

/api/overview

This has the following fields:

cluster_name

The name of the entire cluster, as set with rabbitmqctl set_cluster_name.

contexts

A list of web application contexts in the cluster.

erlang_full_version

A string with extended detail about the Erlang VM and how it was compiled, for the node connected to.

erlang_version

A string with the Erlang version of the node connected to. As clusters should all run the same version this can be taken as representing the cluster.

exchange_types

A list of all exchange types available.

listeners

All (non-HTTP) network listeners for all nodes in the cluster. (See contexts in /api/nodes for HTTP).

management_version

Version of the management plugin in use.

message_stats

A message_stats object for everything the user can see - for all vhosts regardless of permissions in the case of monitoring and administrator users, and for all vhosts the user has access to for other users.

node

The name of the cluster node this management plugin instance is running on.

object_totals

An object containing global counts of all connections, channels, exchanges, queues and consumers, subject to the same visibility rules as for message_stats.

queue_totals

An object containing sums of the messages, messages_ready and messages_unacknowledged fields for all queues, again subject to the same visibility rules as for message_stats.

rabbitmq_version

Version of RabbitMQ on the node which processed this request.

rates_mode

'none', 'basic' or 'detailed'.

statistics_db_event_queue

Number of outstanding statistics events yet to be processed by the database.

statistics_db_node

Name of the cluster node hosting the management statistics database.

/api/nodes

This has the following fields:

applications

List of all Erlang applications running on the node.

auth_mechanisms

List of all SASL authentication mechanisms installed on the node.

cluster_links

A list of the other nodes in the cluster. For each node, there are details of the TCP connection used to connect to it and statistics on data that has been transferred.

config_files

List of config files read by the node.

contexts

List of all HTTP listeners on the node.

db_dir

Location of the persistent storage used by the node.

disk_free

Disk free space in bytes.

disk_free_alarm

Whether the disk alarm has gone off.

disk_free_limit

Point at which the disk alarm will go off.

enabled_plugins

List of plugins which are both explicitly enabled and running.

exchange_types

Exchange types available on the node.

log_files

List of log files used by the node. If the node also sends messages to stdout, "<stdout>" is also reported in the list.

mem_used

Memory used in bytes.

mem_alarm

Whether the memory alarm has gone off.

mem_limit

Point at which the memory alarm will go off.

name

Node name.

net_ticktime

Current kernel net_ticktime setting for the node.

os_pid

Process identifier for the Operating System under which this node is running.

partitions

List of network partitions this node is seeing.

proc_total

Maximum number of Erlang processes.

proc_used

Number of Erlang processes in use.

rates_mode

'none', 'basic' or 'detailed'.

run_queue

Average number of Erlang processes waiting to run.

running

Boolean for whether this node is up. Obviously if this is false, most other stats will be missing.

type

'disc' or 'ram'.

uptime

Time since the Erlang VM started, in milliseconds.

processors

Number of logical CPU cores used by RabbitMQ.

/api/nodes/(name)

All of the above, plus:

memory

Detailed memory use statistics. Only appears if ?memory=true is appended to the URL.

binary

Detailed breakdown of the owners of binary memory. Only appears if ?binary=true is appended to the URL. Note that this can be an expensive query if there are many small binaries in the system.

/api/connections

/api/connections/(name)

See documentation for rabbitmqctl list_connections. No additional fields, although pid is replaced by node.

Note also that while non-AMQP connections will appear in this list (unlike rabbitmqctl list_connections), they will omit many of the connection-level statistics.

/api/connections/(name)/channels

/api/channels

See documentation for rabbitmqctl list_channels, with pid replaced by node, plus:

connection_details

Some basic details about the owning connection.

message_stats

See the section on message_stats above.

/api/channels/(name)

All the above, plus

publishes

Detailed message stats (see section above) for publishes to exchanges.

deliveries

Detailed message stats for deliveries from queues.

consumer_details

List of consumers on this channel, with some details on each.

/api/exchanges

/api/exchanges/(vhost)

See documentation for rabbitmqctl list_exchanges, plus:

message_stats

See the section on message_stats above.

/api/exchanges/(vhost)/(name)

All the above, plus:

incoming

Detailed message stats (see section above) for publishes from channels into this exchange.

outgoing

Detailed message stats for publishes from this exchange into queues.

/api/queues

When using the query parameters combination of disable_stats and enable_queue_totals this query returns the following fields:

name

The name of the queue.

vhost

The name of the virtual host.

type

The type of the queue.

node

Depending on the type of the queue, this is the node which holds the queue or hosts the leader.

state

The status of the queue.

arguments

The arguments of the queue.

auto_delete

The value of the auto_delete argument.

durable

The value of the durable argument.

exclusive

The value of the exclusive argument.

messages

The total number of messages in the queue.

messages_ready

The number of messages ready to be delivered in the queue.

messages_unacknowledged

The number of messages waiting for acknowledgement in the queue.

/api/queues/(vhost)

See documentation for rabbitmqctl list_queues, with all references to pids replaced by nodes plus:

message_stats

See the section on message_stats above.

/api/queues/(vhost)/(name)

All the above, plus:

incoming

Detailed message stats (see section above) for publishes from exchanges into this queue.

deliveries

Detailed message stats for deliveries from this queue into channels.

consumer_details

List of consumers on this channel, with some details on each.

/api/vhosts/

/api/vhosts/(name)

All the fields from rabbitmqctl list_vhosts (i.e. name and tracing) plus:

message_stats

Global message_stats for this vhost. Note that activity for other users in this vhost is shown, even for users without the monitoring tag.

messages messages_ready messages_acknowledged

Sum of these fields for all queues in the vhost.

recv_oct send_oct

Sum of these fields for all connections to the vhost.

Pagination Parameters

The pagination can be applied to the endpoints that list

  • queues
  • exchanges
  • connections
  • channels

Without pagination, these endpoints can produce very large JSON responses and waste a lot of bandwidth and CPU resources.

Default page size is 100, maximum supported page size is 500.

Below are the query parameters that can be used.

Parameter NameData TypeDescription
pagePositive integer

Page number

page_sizePositive integer

Number of elements for page (default value: 100, maximum supported value: 500)

nameString

Filter by name, for example queue name, exchange name etc.

use_regexBoolean

Enables regular expression for the param name

Examples:

http://localhost:15672/api/queues?page=1&page_size=50

Fetches the first queue page with 50 elements

http://localhost:15672/api/queues/my-vhost?page=1&page_size=100&name=&use_regex=false&pagination=true

Filter the first queues page for the virtual host "my-vhost"

http://localhost:15672/api/exchanges?page=1&page_size=100&name=%5Eamq&use_regex=true&pagination=true

Filter the first exchanges page, 100 elements, with named filtered using the regular expression "^amq"