< Submit API issue
API docs by Redocly

EMQX Dedicated REST API (v5)

Download OpenAPI specification:Download

EMQX Dedicated REST API

Actions

Reset action metrics

Reset a bridge metrics by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Manually start a bridge

Start bridge on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Enable or disable bridge

Enable or Disable bridge on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

enable
required
boolean
Example: true

Whether to enable this bridge.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List bridges

List all created bridges.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create bridge

Create a new bridge by type and name.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "timescale"

The Bridge Type

name
required
string

Bridge name.

local_topic
string

MQTT topic or topic filter as data source (action input). If rule action is used as data source, this config should be left empty, otherwise messages will be duplicated in the remote system.

required
object (bridge_pgsql.action_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (actions_and_sources.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Test creating bridge

Test creating a new bridge.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "timescale"

The Bridge Type

name
required
string

Bridge name.

local_topic
string

MQTT topic or topic filter as data source (action input). If rule action is used as data source, this config should be left empty, otherwise messages will be duplicated in the remote system.

required
object (bridge_pgsql.action_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (actions_and_sources.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "message": "string"
}

List available action types

Lists the available action types.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • "http",
  • "rocketmq",
  • "rabbitmq",
  • "cassandra",
  • "influxdb",
  • "greptimedb",
  • "azure_event_hub_producer",
  • "iotdb",
  • "pulsar",
  • "sqlserver",
  • "syskeeper_forwarder",
  • "hstreamdb",
  • "kafka_producer",
  • "confluent_producer",
  • "gcp_pubsub_producer",
  • "mongodb",
  • "kinesis",
  • "datalayers",
  • "s3",
  • "opents",
  • "redis",
  • "mqtt",
  • "timescale",
  • "oracle",
  • "clickhouse",
  • "snowflake",
  • "couchbase",
  • "azure_blob_storage",
  • "tdengine",
  • "matrix",
  • "elasticsearch",
  • "pgsql",
  • "mysql",
  • "dynamo"
]

Get bridge

Get a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Update bridge

Update a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Request Body schema: application/json
One of
local_topic
string

MQTT topic or topic filter as data source (action input). If rule action is used as data source, this config should be left empty, otherwise messages will be duplicated in the remote system.

required
object (bridge_pgsql.action_parameters)
enable
boolean
Default: true

Enable (true) or disable (false) this action.

connector
required
string

Name of the connector specified by the action, used for external resource selection.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

object (actions_and_sources.action_resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "resource_opts": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "my_http_action",
  • "status": "connected",
  • "type": "http",
  • "enable": true,
  • "parameters": {
    },
  • "connector": "my_http_connector",
  • "node_status": [
    ],
  • "resource_opts": {
    }
}

Delete bridge

Delete a bridge by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

query Parameters
also_delete_dep_actions
boolean
Default: false

Whether to cascade delete dependent actions.

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get action metrics

Get bridge metrics by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_action

The bridge id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "metrics": {
    },
  • "node_metrics": [
    ]
}

Authentication

Get user from built-in database authenticator.

Get user from built-in database authenticator.

Authorizations:
basicAuthbearerAuth
path Parameters
user_id
required
string

User ID.

Responses

Response samples

Content type
application/json
Example
{
  • "user_id": "user1"
}

Update user in built-in database authenticator.

Update user in built-in database authenticator.

Authorizations:
basicAuthbearerAuth
path Parameters
user_id
required
string

User ID.

Request Body schema: application/json
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******"
}

Response samples

Content type
application/json
{
  • "regular_user": {
    },
  • "super_user": {
    }
}

Delete user in built-in database authenticator.

Delete user in built-in database authenticator.

Authorizations:
basicAuthbearerAuth
path Parameters
user_id
required
string

User ID.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Import users into built-in database authenticator.

Import users into built-in database authenticator.

Authorizations:
basicAuthbearerAuth
query Parameters
type
required
string
Enum: "plain" "hash"
Example: type=hash

The import file template type, enum with plain,hash

Request Body schema: application/json

Import body

object

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List users in built-in database authenticator.

List users in built-in database authenticator.

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

like_user_id
string

Fuzzy search user_id (username or clientid).

is_superuser
boolean

Is superuser

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create users for built-in database authenticator.

Create users for built-in database authenticator.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
user_id
required
string
password
required
string
is_superuser
boolean
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "password": "******",
  • "user_id": "user1"
}

Response samples

Content type
application/json
Example
{
  • "user_id": "user1"
}

Authorization

Show the list of rules for users

Show the list of rules for users

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

like_username
string

Fuzzy search username as substring

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add new rule for 'username'

Add new rule for 'username'

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
Array of objects (emqx_authz_api_mnesia.rule_item)
username
required
string

Username

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Show the list of rules for clients

Show the list of rules for clients

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

like_clientid
string

Fuzzy search clientid as substring

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add new rule for 'clientid'

Add new rule for 'clientid'

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
Array of objects (emqx_authz_api_mnesia.rule_item)
clientid
required
string

ClientID

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get rule for 'clientid'

Get rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "clientid": "client1"
}

Set rule for 'clientid'

Set rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)
clientid
required
string

ClientID

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ],
  • "clientid": "client1"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Delete rule for 'clientid'

Delete rule for 'clientid'

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Example: client1

ClientID

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Get rule for 'username'

Get rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ],
  • "username": "user1"
}

Set rule for 'username'

Set rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)
username
required
string

Username

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ],
  • "username": "user1"
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Delete rule for 'username'

Delete rule for 'username'

Authorizations:
basicAuthbearerAuth
path Parameters
username
required
string
Example: user1

Username

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Delete all rules for all 'users', 'clients' and 'a

Delete all rules for all 'users', 'clients' and 'all'

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Show the list of rules for 'all'

Show the list of rules for 'all'

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ]
}

Delete rules for 'all'

Delete rules for 'all'

Authorizations:
basicAuthbearerAuth

Responses

Create/Update the list of rules for 'all'.

Create/Update the list of rules for 'all'.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array of objects (emqx_authz_api_mnesia.rule_item)

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Clients

Kick out a batch of client by client IDs

Kick out a batch of client by client IDs

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "emqx_clientid_985bb09d",
  • "emqx_clientid_211cc01c"
]

Get client authz cache in the cluster.

Get client authz cache in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "access": "publish",
  • "result": "allow",
  • "topic": "testtopic/1",
  • "updated_time": 1687850712989
}

Clean client authz cache in the cluster.

Clean client authz cache in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

Get clients info by client ID

Get clients info by client ID

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "heap_size": 610,
  • "send_msg.dropped.expired": 0,
  • "send_oct": 31,
  • "recv_msg.qos1": 0,
  • "is_persistent": false,
  • "send_pkt": 4,
  • "clean_start": true,
  • "inflight_cnt": 0,
  • "node": "emqx@127.0.0.1",
  • "send_msg.dropped.queue_full": 0,
  • "awaiting_rel_cnt": 0,
  • "inflight_max": 32,
  • "created_at": "2024-01-01T12:34:56.789+08:00",
  • "subscriptions_cnt": 1,
  • "mailbox_len": 0,
  • "send_cnt": 4,
  • "connected": true,
  • "ip_address": "127.0.0.1",
  • "awaiting_rel_max": 100,
  • "recv_msg.qos2": 0,
  • "proto_ver": 5,
  • "mountpoint": "null",
  • "proto_name": "MQTT",
  • "durable": false,
  • "port": 52571,
  • "connected_at": "2024-01-01T12:34:56.789+08:00",
  • "enable_authn": true,
  • "expiry_interval": 0,
  • "username": null,
  • "recv_msg": 0,
  • "recv_oct": 49,
  • "send_msg.dropped.too_large": 0,
  • "keepalive": 60,
  • "send_msg.qos1": 0,
  • "send_msg.qos2": 0,
  • "recv_msg.qos0": 0,
  • "send_msg.qos0": 0,
  • "subscriptions_max": "infinity",
  • "mqueue_max": 1000,
  • "mqueue_dropped": 0,
  • "clientid": "01",
  • "is_bridge": false,
  • "peerport": 52571,
  • "send_msg": 0,
  • "listener": "tcp:default",
  • "recv_cnt": 4,
  • "recv_pkt": 4,
  • "recv_msg.dropped": 0,
  • "send_msg.dropped": 0,
  • "recv_msg.dropped.await_pubrel_timeout": 0,
  • "reductions": 6836,
  • "mqueue_len": 0
}

Kick out client by client ID

Kick out client by client ID

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

Unsubscribe bulk

Unsubscribe bulk

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
Array
topic
string

Topic

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

Subscribe bulk

Subscribe bulk

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
Array
topic
required
string

Topic

qos
integer [ 0 .. 2 ]
Default: 0

QoS

nl
integer
Default: 0

No Local

rap
integer
Default: 0

Retain as Published

rh
integer
Default: 0

Retain Handling

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Subscribe

Subscribe

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
topic
required
string

Topic

qos
integer [ 0 .. 2 ]
Default: 0

QoS

nl
integer
Default: 0

No Local

rap
integer
Default: 0

Retain as Published

rh
integer
Default: 0

Retain Handling

Responses

Request samples

Content type
application/json
{
  • "topic": "testtopic/#",
  • "qos": 0,
  • "nl": 0,
  • "rap": 0,
  • "rh": 0
}

Response samples

Content type
application/json
{
  • "node": "emqx@127.0.0.1",
  • "topic": "testtopic/1",
  • "clientid": "emqx_clientid_xx128cdhfc",
  • "qos": 0,
  • "nl": 0,
  • "rap": 0,
  • "rh": 0,
  • "durable": false
}

Get client mqueue messages

Get client mqueue messages

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
query Parameters
payload
string
Default: "base64"
Enum: "none" "base64" "plain"

Client's inflight/mqueue messages payload encoding. If set to none, no payload is returned in the response.

max_payload_bytes
string
Default: "1MB"
Example: max_payload_bytes=32MB

Client's inflight/mqueue messages payload limit. The total payload size of all messages in the response will not exceed this value. Messages beyond the limit will be silently omitted in the response. The only exception to this rule is when the first message payload is already larger than the limit. In this case, the first message will be returned in the response.

string or string or string
Example: position=none

An opaque token that can then be in subsequent requests to get the next chunk of results: "?position={prev_response.meta.position}"
It is used instead of "page" parameter to traverse highly volatile data.
Can be omitted or set to "none" to get the first chunk of data.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get client in-flight messages

Get client in-flight messages

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
query Parameters
payload
string
Default: "base64"
Enum: "none" "base64" "plain"

Client's inflight/mqueue messages payload encoding. If set to none, no payload is returned in the response.

max_payload_bytes
string
Default: "1MB"
Example: max_payload_bytes=32MB

Client's inflight/mqueue messages payload limit. The total payload size of all messages in the response will not exceed this value. Messages beyond the limit will be silently omitted in the response. The only exception to this rule is when the first message payload is already larger than the limit. In this case, the first message will be returned in the response.

string or string or string
Example: position=none

An opaque token that can then be in subsequent requests to get the next chunk of results: "?position={prev_response.meta.position}"
It is used instead of "page" parameter to traverse highly volatile data.
Can be omitted or set to "none" to get the first chunk of data.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Unsubscribe

Unsubscribe

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string
Request Body schema: application/json
topic
string

Topic

Responses

Request samples

Content type
application/json
{
  • "topic": "testtopic/#"
}

Response samples

Content type
application/json
{
  • "code": "CLIENTID_NOT_FOUND",
  • "message": "string"
}

Get client subscriptions

Get client subscriptions

Authorizations:
basicAuthbearerAuth
path Parameters
clientid
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List clients

List clients

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

node
string
Example: node=emqx@127.0.0.1

Node name

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

username
Array of strings

User name, multiple values can be specified by repeating the parameter: username=u1&username=u2

ip_address
string
Example: ip_address=127.0.0.1

Client's IP address

conn_state
string
Enum: "connected" "idle" "disconnected"

The current connection status of the client, the possible values are connected,idle,disconnected

clean_start
boolean

Whether the client uses a new session

proto_ver
string

Client protocol version

like_clientid
string

Fuzzy search clientid as substring

like_username
string

Fuzzy search username as substring

integer or string

Search client session creation time by greater than or equal method, rfc3339 or timestamp(millisecond)

integer or string

Search client session creation time by less than or equal method, rfc3339 or timestamp(millisecond)

integer or string

Search client connection creation time by greater than or equal method, rfc3339 or timestamp(epoch millisecond)

integer or string

Search client connection creation time by less than or equal method, rfc3339 or timestamp(millisecond)

clientid
Array of strings

Client ID, multiple values can be specified by repeating the parameter: clientid=c1&clientid=c2

Array of strings or string
Default: "all"

Comma separated list of client fields to return in the response

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Connectors

Test creating connector

Test creating a new connector.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "timescale"

The type of the connector.

name
required
string

The name of the connector.

enable
boolean
Default: true

Enable (true) or disable (false) this connector.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The PostgreSQL default port 5432 is used if [:Port] is not specified.

disable_prepared_statements
boolean
Default: false

Disables the usage of prepared statements in the connections.
Some endpoints, like PGBouncer or Supabase in Transaction mode, do not
support session features such as prepared statements. For such connections,
this option should be enabled.

database
required
string

Database name.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

auto_reconnect
boolean
Deprecated
Default: true

Deprecated. Enable automatic reconnect to the database.

object (emqx.ssl_client_opts)
object (connector_postgres.resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    }
}

Response samples

Content type
application/json
{
  • "code": "TEST_FAILED",
  • "message": "string"
}

Get connector

Get a connector by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "status": "connected",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    },
  • "node_status": [
    ],
  • "actions": [
    ]
}

Update connector

Update a connector by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

Request Body schema: application/json
One of
enable
boolean
Default: true

Enable (true) or disable (false) this connector.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The PostgreSQL default port 5432 is used if [:Port] is not specified.

disable_prepared_statements
boolean
Default: false

Disables the usage of prepared statements in the connections.
Some endpoints, like PGBouncer or Supabase in Transaction mode, do not
support session features such as prepared statements. For such connections,
this option should be enabled.

database
required
string

Database name.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

auto_reconnect
boolean
Deprecated
Default: true

Deprecated. Enable automatic reconnect to the database.

object (emqx.ssl_client_opts)
object (connector_postgres.resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "status": "connected",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    },
  • "node_status": [
    ],
  • "actions": [
    ]
}

Delete connector

Delete a connector by id.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Manually start a connector

Start connector on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

operation
required
string
Value: "start"
Example: start

Operation can be one of: 'start'.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Enable or disable connector

Enable or Disable connector on all nodes in the cluster.

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: http:my_http_connector

The connector id. Must be of format {type}:{name}.

enable
required
boolean
Example: true

Whether to enable this connector.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

List connectors

List all created connectors.

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {},
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {},
  • {
    },
  • {
    }
]

Create connector

Create a new connector by type and name.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
type
required
string
Value: "timescale"

The type of the connector.

name
required
string

The name of the connector.

enable
boolean
Default: true

Enable (true) or disable (false) this connector.

tags
Array of strings

Tags to annotate this config entry.

description
string
Default: ""

Descriptive text.

server
required
string

The IPv4 or IPv6 address or the hostname to connect to.

A host entry has the following form: Host[:Port].

The PostgreSQL default port 5432 is used if [:Port] is not specified.

disable_prepared_statements
boolean
Default: false

Disables the usage of prepared statements in the connections.
Some endpoints, like PGBouncer or Supabase in Transaction mode, do not
support session features such as prepared statements. For such connections,
this option should be enabled.

database
required
string

Database name.

pool_size
integer >= 1
Default: 8

Size of the connection pool towards the bridge target service.

username
required
string

The username associated with the bridge in the external database used for authentication or identification purposes.

password
string <password>

The password associated with the bridge, used for authentication with the external database.

auto_reconnect
boolean
Deprecated
Default: true

Deprecated. Enable automatic reconnect to the database.

object (emqx.ssl_client_opts)
object (connector_postgres.resource_opts)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "influxdb_connector",
  • "status": "connected",
  • "type": "influxdb",
  • "ssl": {
    },
  • "description": "My example influxdb connector",
  • "server": "127.0.0.1:8086",
  • "enable": true,
  • "parameters": {
    },
  • "node_status": [
    ],
  • "actions": [
    ]
}

Schema Registry

List registered schemas

List all registered schemas

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Register a new schema

Register a new schema

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
One of
name
required
string

A name for the schema that will serve as its identifier.

type
required
string
Value: "json"

Must be json for JSON schema.

source
required
string

Source text for the schema.

description
string
Default: ""

A description for this schema.

Responses

Request samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Response samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Get registered schema

Get a schema by its name

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

The schema name

Responses

Response samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Update a schema

Update an existing schema

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

The schema name

Request Body schema: application/json
One of
type
required
string
Value: "json"

Must be json for JSON schema.

source
required
string

Source text for the schema.

description
string
Default: ""

A description for this schema.

Responses

Request samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Response samples

Content type
application/json
{
  • "name": "my_avro_schema",
  • "type": "avro",
  • "description": "My Avro Schema",
  • "source": "{\"type\":\"record\",\"fields\":[{\"type\":\"int\",\"name\":\"i\"},{\"type\":\"string\",\"name\":\"s\"}]}"
}

Delete registered schema

Delete a schema

Authorizations:
basicAuthbearerAuth
path Parameters
name
required
string
Example: my_schema

The schema name

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Publish

Publish a batch of messages

Possible HTTP response status code are:

200: All messages are delivered to at least one subscriber;

202: At least one message was not delivered to any subscriber;

400: At least one message is invalid. For example bad topic name, or QoS is out of range;

503: Failed to deliver at least one of the messages;


In case there is at lest one invalid message in the batch, the HTTP response body
is the same as for /publish API.

Otherwise the HTTP response body is an array of JSON objects indicating the publish
result of each individual message in the batch.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
Array
payload_encoding
string
Default: "plain"
Enum: "plain" "base64"

MQTT Payload Encoding, base64 or plain. When set to base64, the message is decoded before it is published.

topic
required
string

Topic Name

qos
integer [ 0 .. 2 ]
Default: 0

MQTT message QoS

clientid
string
Deprecated
payload
required
string

The MQTT message payload.

object (emqx_mgmt_api_publish.message_properties)
retain
boolean
Default: false

A boolean field to indicate if this message should be retained.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Publish a message

Possible HTTP status response codes are:

200: The message is delivered to at least one subscriber;

202: No matched subscribers;

400: Message is invalid. for example bad topic name, or QoS is out of range;

503: Failed to deliver the message to subscriber(s)

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
payload_encoding
string
Default: "plain"
Enum: "plain" "base64"

MQTT Payload Encoding, base64 or plain. When set to base64, the message is decoded before it is published.

topic
required
string

Topic Name

qos
integer [ 0 .. 2 ]
Default: 0

MQTT message QoS

clientid
string
Deprecated
payload
required
string

The MQTT message payload.

object (emqx_mgmt_api_publish.message_properties)
retain
boolean
Default: false

A boolean field to indicate if this message should be retained.

Responses

Request samples

Content type
application/json
{
  • "payload_encoding": "plain",
  • "topic": "api/example/topic",
  • "qos": 0,
  • "clientid": "string",
  • "payload": "hello emqx api",
  • "properties": {
    },
  • "retain": false
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Rules

Apply a rule for testing

Apply a rule with the given message and environment

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id
Request Body schema: application/json
rule_engine.ctx_message_transformation_failed (object) or rule_engine.ctx_schema_validation_failed (object) or rule_engine.ctx_delivery_dropped (object) or rule_engine.ctx_bridge_mqtt (object) or rule_engine.ctx_check_authn_complete (object) or rule_engine.ctx_check_authz_complete (object) or rule_engine.ctx_connack (object) or rule_engine.ctx_disconnected (object) or rule_engine.ctx_connected (object) or rule_engine.ctx_dropped (object) or rule_engine.ctx_acked (object) or rule_engine.ctx_delivered (object) or rule_engine.ctx_unsub (object) or rule_engine.ctx_sub (object) or rule_engine.ctx_pub (object)
Default: {}

The context of the event for testing

stop_action_after_template_rendering
boolean
Default: true

Set this to true if the action should be stopped after its template has been rendered (default is true).

Responses

Request samples

Content type
application/json
{
  • "context": { },
  • "stop_action_after_template_rendering": true
}

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

List rules

List all rules

Authorizations:
basicAuthbearerAuth
query Parameters
enable
boolean

Filter enable/disable rules

from
string

Filter rules by from(topic), exact match

like_id
string

Filter rules by id, Substring matching

like_from
string

Filter rules by from(topic), Substring matching

like_description
string

Filter rules by description, Substring matching

match_from
string

Filter rules by from(topic), Mqtt topic matching

action
Array of strings

Filters rules that contain any of the given action id(s). When used in conjunction with source id filtering, the rules must contain sources and actions that match some of the criteria.

source
Array of strings

Filters rules that contain any of the given source id(s). When used in conjunction with action id filtering, the rules must contain sources and actions that match some of the criteria.

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a rule

Create a new rule using given Id

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
name
string
Default: ""

The name of the rule

sql
required
string

SQL query to transform the messages.
Example: SELECT * FROM "test/topic" WHERE payload.x = 1

Array of rule_engine.user_provided_function (object) or rule_engine.builtin_action_console (object) or rule_engine.builtin_action_republish (object) or strings
Default: []

A list of actions of the rule.
An action can be a string that refers to the channel ID of an EMQX bridge, or an object
that refers to a function.
There a some built-in functions like "republish" and "console", and we also support user
provided functions in the format: "{module}:{function}".
The actions in the list are executed sequentially.
This means that if one of the action is executing slowly, all the following actions will not
be executed until it returns.
If one of the action crashed, all other actions come after it will still be executed, in the
original order.
If there's any error when running an action, there will be an error message, and the 'failure'
counter of the function action or the bridge channel will increase.

enable
boolean
Default: true

Enable or disable the rule

description
string
Default: ""

The description of the rule

metadata
object

Rule metadata, do not change manually

Responses

Request samples

Content type
application/json
{
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Get rule metrics

Get a rule's metrics by given Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "metrics": {
    },
  • "node_metrics": [
    ]
}

List rule events

List all events can be used in rules

Authorizations:
basicAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "event": "$events/client_connected",
  • "title": "some title",
  • "description": "some desc",
  • "columns": { },
  • "test_columns": { },
  • "sql_example": "string"
}

Reset rule metrics

Reset a rule metrics

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Get rule

Get a rule by given Id

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Update rule

Update a rule by given Id to all nodes in the cluster

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id
Request Body schema: application/json
name
string
Default: ""

The name of the rule

sql
required
string

SQL query to transform the messages.
Example: SELECT * FROM "test/topic" WHERE payload.x = 1

Array of rule_engine.user_provided_function (object) or rule_engine.builtin_action_console (object) or rule_engine.builtin_action_republish (object) or strings
Default: []

A list of actions of the rule.
An action can be a string that refers to the channel ID of an EMQX bridge, or an object
that refers to a function.
There a some built-in functions like "republish" and "console", and we also support user
provided functions in the format: "{module}:{function}".
The actions in the list are executed sequentially.
This means that if one of the action is executing slowly, all the following actions will not
be executed until it returns.
If one of the action crashed, all other actions come after it will still be executed, in the
original order.
If there's any error when running an action, there will be an error message, and the 'failure'
counter of the function action or the bridge channel will increase.

enable
boolean
Default: true

Enable or disable the rule

description
string
Default: ""

The description of the rule

metadata
object

Rule metadata, do not change manually

Responses

Request samples

Content type
application/json
{
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "id": "293fb66f",
  • "from": "t/#",
  • "created_at": "2021-12-01T15:00:43.153+08:00",
  • "name": "foo",
  • "sql": "SELECT * FROM \"test/topic\" WHERE payload.x = 1",
  • "actions": [
    ],
  • "enable": true,
  • "description": "Some description",
  • "metadata": { }
}

Delete rule

Delete a rule by given Id from all nodes in the cluster

Authorizations:
basicAuthbearerAuth
path Parameters
id
required
string
Example: my_rule_id

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}

Retainer

List retained messages.

List retained messages.

Authorizations:
basicAuthbearerAuth
query Parameters
topic
string

Topic filter, supports wildcards, omit this to match all messages.

page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Delete all retained messages

Delete all retained messages

Authorizations:
basicAuthbearerAuth

Responses

Lookup a message by a topic without wildcards.

Lookup a message by a topic without wildcards.

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic.

Responses

Response samples

Content type
application/json
{
  • "payload": "string",
  • "msgid": "string",
  • "topic": "string",
  • "qos": 0,
  • "publish_at": "string",
  • "from_clientid": "string",
  • "from_username": "string"
}

Delete matching messages.

Delete matching messages.

Authorizations:
basicAuthbearerAuth
path Parameters
topic
required
string

Topic.

Responses

Response samples

Content type
application/json
{
  • "code": "BAD_REQUEST",
  • "message": "string"
}

Subscriptions

List subscriptions

List subscriptions

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

node
string
Example: node=emqx@127.0.0.1

Node name

clientid
string

Client ID

qos
integer [ 0 .. 2 ]
Example: qos=0

QoS

topic
string

Topic, url encoding

match_topic
string

Match topic string, url encoding

share_group
string

Shared subscription group name

durable
boolean

Filter subscriptions by durability

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Banned

List all currently banned client IDs, usernames an

List all currently banned client IDs, usernames and IP addresses.
Filters are supported. Since filters are mutually exclusive, only one filter is allowed in a query.

Authorizations:
basicAuthbearerAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number of the results to fetch.

limit
integer [ 1 .. 10000 ]
Default: 100
Example: limit=50

Results per page(max 10000)

clientid
string

Query the banned objects with an exact client ID.

username
string

Query the banned objects with an exact username.

peerhost
string
Example: peerhost=127.0.0.1

Query the banned objects with an exact IP address.

like_clientid
string

Fuzzy query banned objects with a regular expression for client ID.

like_username
string

Fuzzy query banned objects with a regular expression for username.

like_peerhost
string
Example: like_peerhost=127.0.0.1

Fuzzy query banned objects with a regular expression for IP address.

like_peerhost_net
string
Example: like_peerhost_net=192.1.0.0/16

Fuzzy query banned objects with a regular expression for CIDR.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Clear all banned data.

Clear all banned data.

Authorizations:
basicAuthbearerAuth

Responses

Add a client ID, username or IP address to the bla

Add a client ID, username or IP address to the blacklist.

Authorizations:
basicAuthbearerAuth
Request Body schema: application/json
as
required
string
Enum: "clientid" "username" "peerhost" "clientid_re" "username_re" "peerhost_net"

Ban method, which can be exact client ID, client ID regular expression, exact username, username regular expression,
IP address or an IP address range.

who
required
string

Ban object, specific client ID, username or IP address.

by
string

Initiator of the ban.

reason
string

Ban reason, record the reason why the current object was banned.

integer or string

The start time of the ban, the format is rfc3339, the default is the time when the operation was initiated.

(integer or string) or string
Default: "infinity"

The end time of the ban, the format is rfc3339, the default is the time when the operation was initiated + 1 year.

Responses

Request samples

Content type
application/json
{
  • "as": "username",
  • "who": "Banned name",
  • "by": "mgmt_api",
  • "reason": "Too many requests",
  • "at": "2021-10-25T21:48:47+08:00",
  • "until": "2021-10-25T21:53:47+08:00"
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Remove a client ID, username or IP address from th

Remove a client ID, username or IP address from the blacklist.

Authorizations:
basicAuthbearerAuth
path Parameters
as
required
string
Enum: "clientid" "username" "peerhost" "clientid_re" "username_re" "peerhost_net"
Example: username

Ban method, which can be exact client ID, client ID regular expression, exact username, username regular expression,
IP address or an IP address range.

who
required
string
Example: Badass

Ban object, specific client ID, username or IP address.

Responses

Response samples

Content type
application/json
{
  • "code": "NOT_FOUND",
  • "message": "string"
}