Skip to main content
Technical Preview

​
Overview

Infraspeak is a maintenance management platform (CMMS) for work orders, planned maintenance, assets, locations, stock and procurement. Its Public REST API v3 (https://api.infraspeak.com/v3) is documented on the Infraspeak Developer Portal, with an official OpenAPI spec behind the API Reference. The API uses Infraspeak’s own names for some objects. A work order is a Failure (/failures), an asset is an Element (/elements), a planned job is a Work (/works), and a planned job order is a Scheduled Work (/works/scheduled). The topics below use the names you see in the Infraspeak app (work-order, asset, planned-job, planned-job-order). The InfraspeakApi connector maps 22 MQTT topics onto that API. Typical uses: open a work order when an alarm is raised, add live readings to its observations, poll open work orders back onto the broker, read an asset’s metering statistics, and move a planned job order when a line stops. Each event publishes the Infraspeak reply on <topic>/response.

​
Prerequisites

  • An Infraspeak account, and a Personal Access Token (PAT) from Infraspeak. Infraspeak issues tokens on request: ask for a sandbox token first (describe your application and integration), then for a production token once the integration is validated. Sandbox and production tokens are separate. A token from one environment does not work in the other.
  • The PAT acts as a “System” user of your account. Changes it makes show up in the Infraspeak history as that user. It needs permission for the objects you call: work orders, assets, locations, clients, problems and planned jobs.
  • The ids your account uses: a client_id, a problem_id (a Problem Type, not an Area), and a local_id. The local_id must be a location of type location, not a building or location-folder.
  • Outbound HTTPS from the broker to api.infraspeak.com (or api.sandbox.infraspeak.com).

​
Authentication

Every event sends Authorization: {value.json.authorization}, so the payload carries the full header value Bearer <PAT>. Store it as a Hub secret, for example INFRASPEAK_AUTHORIZATION, and read it with GET SECRET in the action that publishes to the connector. A missing or invalid token returns 401 with "Authentication token invalid.". A valid token without permission returns 403. The connector also sends Accept: application/json and a User-Agent that names the integration. Infraspeak asks integrations to identify themselves this way. Put your own contact in a fork.

​
Configuration

List events take the whole query string in query. Infraspeak’s filter syntax: Responses use a JSON:API shape: {"data": {"type", "id", "attributes"}, "meta": {"pagination"}, "links"}. Errors look like {"status": "error", "error": {"http_code", "message", "properties"}}.

​
Basic Syntax

​
Examples

Publish directly to a connector topic:
to cmms/infraspeak/work-order/create, then read cmms/infraspeak/work-order/create/response. The new work order starts in state WAITING_APPROVAL. Actions that feed the connector from plant data:
Restrict who can publish to cmms/infraspeak/# with a rule. These payloads carry the token and can create and delete work orders.

​
Work order states

WAITING_APPROVAL → WAITING_RESOLUTION (approved) → IN_RESOLUTION (started) → PAUSED / COMPLETED. Deleting a work order moves it to ARCHIVED. ListOpenWorkOrders returns everything except COMPLETED and ARCHIVED. ListClosedWorkOrders returns COMPLETED. The public API has no call to approve, start, pause or close a work order. UpdateWorkOrder changes fields only, so technicians drive state changes in the Infraspeak app. Priorities are integers: 1 low, 2 normal, 3 high (same day), 4 critical.

​
Webhooks

Infraspeak webhooks are set up in the Infraspeak web app (Settings → Integrations → Webhooks), not through the API. Events include FAILURE_CREATED, FAILURE_STATE_CHANGED, FAILURE_CLOSED, ELEMENT_UPDATED and others. Deliveries are POST (or PUT) with the resource in data, an X-Is-Topic header naming the event, and an optional HMAC-SHA256 signature in X-Hook-Secret. Receiving them needs a separate connector with ENABLE_SERVER reachable from the internet. That connector is not packaged here.

​
Notes

  • Rate limit: 60 requests per minute per token, on a rolling window. Above that the API returns 429 with Retry-After. Poll every few minutes, or use webhooks.
  • Meter readings: the public v3 API documents no endpoint for writing meter readings. GetAsset with query showMeteringData=true returns each asset meter’s statistics (min, max, average, last value). Infraspeak’s IoT and meter ingestion is not in the public spec, so this connector does not package it.
  • Work orders and assets: CreateWorkOrder takes a location (local_id), not an asset. The public spec has no asset field on create. Put the asset code in description or observations.
  • GetAsset can answer 302 when the asset you asked for was merged into a network element.
  • Errors come back on the response topic: 400 validation (field errors in error.properties), 401 bad token, 403 permission, 404 unknown id or path, 405 wrong method (for example PUT, which the API does not use), 429 rate limit.

​
Testing

The connector passes static checks against the official OpenAPI spec and a local contract mock that covers all 22 events. It was also probed against the real API without a token: every event returns 401 Authentication token invalid., while unknown paths return 404. A run with a real token (sandbox or production) and a broker MQTT round-trip are still open.

​
Not covered

Stock, warehouses and materials, buy and sell orders, quotes, suppliers, cost centers, other costs, files, requests, creating and editing planned jobs, and the webhook receiver. All of these except the webhook receiver are in the Infraspeak API and can be added in a fork.
Last modified on October 21, 2026