--- title: MaintainX API slug: litmusedge/product-features/integration/integration-connectors/maintainx/maintainx-api docTags: createdAt: 2026-09-04T20:01:24.237Z --- The MaintainX API connector publishes meter readings from Litmus Edge (LE) topics to the MaintainX REST API v1. Each outbound message becomes a MaintainX meter-reading request (`POST /meterreadings`), and the response is published back to a local topic for downstream pipelines. For more information, see [MaintainX API Integration Guide](docId\:KKSf1DYUbihvyymuj4P3Y). ## Supported communication - Outbound (publish LE data to MaintainX): Yes - Local topic subscription (trigger the outbound request from an LE topic): Yes - Response capture (publish the MaintainX response to a local topic): Yes - Analytics IT Hub support: Yes ## Authentication The connector authenticates with a MaintainX API bearer token, which is a JWT issued from **Settings** > **Integrations** > **API Keys** in MaintainX. Every request carries the token in an `Authorization: bearer ` header. If you set **Organization ID**, the connector also sends an `x-organization-id: ` header. Set it when your token is scoped to more than one organization. ## Connector configuration :::hint{type="warning"} **Caution:** Setting **Connection Checking Interval (s)** to `0` disables the periodic check entirely. The connector runs no health probe, does not reconnect automatically, and does not detect an outage. A failed initial connection or a mid-run endpoint failure leaves the connector stuck until you restart or reconfigure it. ::: | Field | Type | Description | Required | Default | | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | --------------------------------- | | Name | String | Name of this connector instance. | Yes | `-` | | MaintainX Base URL | String | Base URL for the MaintainX API. Override it only for a sandbox or staging environment. | Yes | `https://api.getmaintainx.com/v1` | | Bearer Token | String (Secret) | MaintainX API token (JWT). Create it in MaintainX under **System** >** Access Control **> **Tokens**. The connector sends it in an `Authorization: bearer ` header. | Yes | `-` | | Organization ID | String | Organization the token applies to. Set it only when your token is scoped to more than one organization. The connector sends it in an `x-organization-id` header. | No | `-` | | Response Topic | String | Local topic that receives the MaintainX response for each request. Leave it empty if you do not need the responses. | No | `-` | | Response Mode | Dropdown | Contents of the response envelope. `body_only` publishes the correlation ID, status code, and body. `full_metadata` adds headers, latency, and any error. | No | `body_only` | | Parallel Publish Count | Integer | Number of messages the connector publishes in parallel. Higher values increase throughput and resource use. Range is `10` to `4000`. | No | `100` | | Request Timeout (s) | Integer | Time in seconds the connector waits for a response before it abandons a request. Range is `1` to `60`. | No | `10` | | Retry Count | Integer | Maximum number of retries after a transport error, a `5xx` response, or a `429` response. Range is `0` to `10`. | No | `0` | | Retry Backoff | Dropdown | Delay pattern between retries: `none`, `fixed`, or `exponential`. The connector honors a `Retry-After` header on a `429` response. | No | `exponential` | | Connection Checking Interval (s) | Integer | How often, in seconds, the connector checks that the MaintainX endpoint is reachable. Range is `0` to `3600`. | No | `300` | ## Additional attributes | Field | Type | Description | Required | Default | | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | | Throttling limit | Integer | Maximum outbound messages per second. A value of `0` disables throttling. MaintainX meter-reading endpoints allow approximately 100 requests every 60 seconds. | No | `0` | | Persistent storage | Boolean | Buffer undelivered messages on disk so they survive a restart or a lost connection. When disabled, the connector holds messages in memory only and loses them if it stops. | No | Disabled | | Persistent storage size limit | Integer | Maximum disk space in GB used for buffered messages. Minimum is `1`. | Yes | `1` | | Queue Mode | Dropdown | Order in which the connector sends buffered messages after a connection is restored. LIFO sends the newest data first. FIFO preserves the original order. | No | `lifo` | | Enable Logging | Boolean | ** | No | Disabled | ## Outbound Subscription to update meter readings When defining an outbound subscription, the connector will make the POST /meterreading API call to MaintanX. The connector expects a JSON object on the local topic, and validates the following keys on the incoming DeviceHub, Analytics or Digital Twins payload. | Key | Required | Maps to | Notes | | ------------------ | ----------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `value` | Yes | `value` in the MaintainX request body | A JSON number, or a string shaped like an integer or a float. | | `timestamp` | Yes | `readingDate` in the MaintainX request body | An ISO 8601 string such as `2026-07-28T14:32:11Z`, or a Unix epoch number in seconds or milliseconds. The connector normalizes it to RFC 3339 UTC before sending. | | `success` | No | Drop gate only | If `success` is present and `false`, the connector drops the message and increments the drop count. A DeviceHub reading marked as failed does not create a MaintainX reading. A missing or `true` value accepts the message. | | `metadata.meterId` | Conditional | `meterId` in the MaintainX request body | Required only when the outbound topic's **Remote Data Topic** is empty. Accepts an integer such as `53` or an integer-valued string such as `"53"`, because DeviceHub metadata values are always strings. | The following payload is accepted: ```json { "value": 120, "timestamp": "2022-01-01T00:00:00.000Z", "success": true, "metadata": { "meterId": "53" } } ``` ### Meter ID sourcing The connector resolves the `meterId` it sends to MaintainX in the following order: 1. **Remote Data Topic.** Set the outbound topic's **Remote Data Topic** to the meter ID, such as `53`. The connector parses it as an integer. This is the preferred method. 2. **Payload metadata.** If **Remote Data Topic** is empty, the connector reads `metadata.meterId` from the incoming payload. Both `53` and `"53"` are accepted. If neither is present, or the value is not an integer, the connector drops the message and increments the drop count. ### Request body The connector builds an array of one reading and posts it to `/meterreadings`: ```json [ { "meterId": 53, "value": 120, "readingDate": "2022-01-01T00:00:00.000Z" } ] ``` ## Analytics IT Hub The connector supports ad-hoc MaintainX API calls through the Analytics IT Hub processor. User can either define a static body in the IT Hub processor configuration or pass the `method`, `path`, `query`, `headers`, and `body` dynamically as a input to the IT Hub processor. Using a JavaScript Processor and IT Hub, users can generating the following output and send it to IT Hub to make a GET /meters/\ call to get details on a specific meter in MaintainX All MaintainX supported API calls are supported by Analytics IT Hub - [https://api.getmaintainx.com/v1/docs](https://api.getmaintainx.com/v1/docs) ```json result = { body: JSON.stringify({ method: "GET", path: "/meters/778324", }) }; ``` POST /meters API call to create a new meter ```json result = { body: JSON.stringify({ method: "POST", path: "/meters", body: { "name": "new_temp_mete", "description": "This meter is used for monitoring the temperature of the boiler", "measurementType": "AUTOMATED_SENSOR", "unit": "Celsius" } }) }; ``` :::hint{type="info"} **Note:** Input into IT Hub, needs to be a JSON string object called body, with the API method, path and request body. As shown in the examples above. ::: The connector rejects the following payloads before it sends any HTTP request. The response topic receives an `ERROR` terminator explaining what is missing. | Payload | Why it is rejected | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Empty, or whitespace only | Nothing was forwarded. If the call comes from a JavaScript processor, use `JSON.stringify` to put the spec into `body`. | | `{}`, `{"method":"GET"}`, `{"method":"GET","query":{...}}` | Neither `path` nor `body` is present. | | `{"path":"/locations"}`, `{"body":[...]}` | No `method` is present. | | `[{...}]` | A bare array cannot carry a `method`. Wrap it in a spec object. | Nothing is defaulted into a write, because `POST /meterreadings` is rate-limited by MaintainX and shares that limit with live tag streaming. An under-specified ad-hoc call would spend that limit on rejected requests. The connector streams every response to the request's response topic as a single data envelope followed by a terminator. ## Response envelope The connector publishes the MaintainX response to the configured response topic. That topic can be the connector-level **Response Topic**, the per-topic response topic, both, or neither. In `body_only` mode: ```json { "correlationId": "...", "statusCode": 201, "body": { ... } } ``` In `full_metadata` mode: ```json { "correlationId": "...", "statusCode": 201, "headers": { "Content-Type": "application/json" }, "latencyMs": 142, "body": { ... }, "error": null } ``` The connector parses JSON response bodies and forwards them as objects. It forwards a non-JSON body as a string. On an error, the `error` field carries a structured message. A message dropped before the request is sent publishes no envelope, because the connector made no HTTP request. This applies to a payload with `success: false` and to a payload missing `value`, `timestamp`, or a meter ID. ## Related topics - [MaintainX API Integration Guide](docId\:KKSf1DYUbihvyymuj4P3Y) - [Add a Connector](docId:4YVfCEP7GYScJHMKYFCuM) - [Manage Connectors](docId\:tQoP7QtquSQqDq9yhbJ34)