MaintainX API

13 min

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.

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 <token> header.

If you set Organization ID, the connector also sends an x-organization-id: <organizationId> header. Set it when your token is scoped to more than one organization.

Connector configuration

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 <token> 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:

{
  "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:

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.

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:

[
  {
    "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/<id> 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

result = {
   body: JSON.stringify({
     method: "GET",
     path: "/meters/778324",
   })
 };

POST /meters API call to create a new meter

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"
    }
  })
};

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:

{
  "correlationId": "...",
  "statusCode": 201,
  "body": { ... }
}

In full_metadata mode:

{
  "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.

MaintainX API Integration Guide

Add a Connector

Manage Connectors