API Reference

The MQCentral API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Getting Started

To begin using the API, you'll need a Client ID and Client Secret. Follow the steps in our Authentication & API Access guide to make your first request.

Base URL

https://api.machineq.net

Authentication

The MQCentral API uses bearer tokens to authenticate requests. To get a bearer token, you need to use your account's Client ID and Client Secret to authenticate through the "get token" API. A successful response will include your bearer token, which you must include with every API request you make.

Your client credentials carry many privileges, so be sure to keep them secure! Do not share your secret Client ID and Client Secret in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authenticated Request

curl https://api.machineq.net/v1/endpoint \
  -H "Authorization: Bearer eyJhbGciSR5cC...kpXVCIstpZeGYeVg" \
  -H "Content-Type: application/json"

Errors

MQCentral uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Code in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a parameter key was spelled wrong, etc.). Codes in the 5xx range indicate an error with MQCentral's servers (these are rare).

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

HTTP Error Codes

                
                        200
                        OK
                        Everything worked as expected.
                    
                        400
                        Bad Request
                        The request was unacceptable, often due to missing a required parameter.
                    
                        401
                        Unauthorized
                        No valid Client Credential provided.
                    
                        402
                        Request Failed
                        The parameters were valid but the request failed.
                    
                        403
                        Forbidden
                        The bearer token doesn’t have permissions to perform the request.
                    
                        404
                        Not Found
                        The requested resource doesn’t exist.
                    
                        409
                        Conflict
                        The request conflicts with another request (perhaps due to using the same idempotent
                            key).
                        
                        424
                        External Dependency Failed
                        The request couldn’t be completed due to a failure in a dependency external to
                            MQCentral.
                        
                        429
                        Too Many Requests
                        Too many requests hit the API too quickly. We recommend an exponential backoff of
                            your requests.
                        
                        500, 502, 503, 504
                        Server Errors
                        Something went wrong on MQCentral’s end. (These are rare.)

200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid Client Credential provided.
402	Request Failed	The parameters were valid but the request failed.
403	Forbidden	The bearer token doesn’t have permissions to perform the request.
404	Not Found	The requested resource doesn’t exist.
409	Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
424	External Dependency Failed	The request couldn’t be completed due to a failure in a dependency external to MQCentral.
429	Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504	Server Errors	Something went wrong on MQCentral’s end. (These are rare.)

Devices

Select endpoints for the Devices API are available in the V2 release. All other APIs continue to use the v1 designation until updated to v2. The V1 Devices API remains available for backwards compatibility.

Results from these endpoints are streamed. After calculating the meta section, the server begins streaming results per Device as the query completes. Streaming enables faster response times for customers with large fleets.

Statistics fields are included at the top-level of each record for easier querying.

Groups are included in each record to support fleet management and filtering.

Endpoints

                GET/v2/devices
GET/v2/devices/{dev_eui}

The Devices object

Attributes

name string

Human-readable name of the Device. Required. Must be unique within the account.

dev_eui string

Extended Unique Identifier (EUI-64) of the device. Required. Must be a 16-character hexadecimal string.

owner_id string

Identifies the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

activation_type enum (string)

Activation method used by the device. Required.

ABP: Activation By Personalization — device keys are hardcoded.
OTAA: Over-The-Air Activation — device keys are negotiated via a join procedure.

service_profile string

Unique identifier of the ServiceProfile assigned to the device. Required. Retrieve applicable values via GET /v1/serviceprofiles.

device_profile string

Unique identifier of the DeviceProfile assigned to the device. Required. Retrieve applicable values via GET /v1/deviceprofiles.

decoder_type string

Unique identifier of the Decoder used to decode packets from the device. Optional. Retrieve applicable values via GET /v1/decodertypes.

output_profile string

Unique identifier of the OutputProfile used for routing packets to external servers. Optional. Retrieve applicable values via GET /v1/outputprofiles.

private_data boolean

Whether device data is private. True means data is not stored; false means data is stored for future processing.

created_at string (date-time)

Timestamp of Device creation in RFC 3339 format.

updated_at string (date-time)

Timestamp of the last Device modification in RFC 3339 format.

updated_by string

Unique identifier of the User or Subscriber that last modified the Device.

last_uplink string (date-time)

Timestamp of the last uplink message from the Device in RFC 3339 format. Null if the device has never sent an uplink.

health_state enum (string)

Calculated health of the Device based on recent activity.

good: Device is performing well with strong signal quality.
fair: Device is operational but with degraded signal quality.
poor: Device is experiencing significant signal degradation.
offline: Device has not communicated recently.

spreading_factor integer

Current LoRa Spreading Factor of the device (e.g., 7 = SF7). Range: 7–12.

average_rssi float

Average Received Signal Strength Indicator (RSSI) over the last 24 hours, in dBm.

average_esp float

Average Estimated Signal Power (ESP) over the last 24 hours, in dBm.

average_snr float

Average Signal-to-Noise Ratio (SNR) over the last 24 hours, in dB.

packet_error_rate float

Percentage of dropped packets over the last 24 hours. Range: 0–100.

battery_level integer

Reported battery level from the Device. Null if the device does not report battery status.

average_weekly_packets integer

Average number of packets per day over the past week.

groups array of objects

List of Groups to which the Device belongs.

The Devices object

{
  "name": "string",
  "dev_eui": "string",
  "owner_id": "string",
  "activation_type": "string",
  "service_profile": "string",
  "device_profile": "string",
  "decoder_type": "string",
  "output_profile": "string",
  "private_data": true,
  "created_at": "2006-01-02T15:04:05.000Z",
  "updated_at": "2006-01-02T15:04:05.000Z",
  "updated_by": "string",
  "last_uplink": "2006-01-02T15:04:05.000Z",
  "health_state": "string",
  "spreading_factor": 0,
  "average_rssi": 0.0,
  "average_esp": 0.0,
  "average_snr": 0.0,
  "packet_error_rate": 0.0,
  "battery_level": 0,
  "average_weekly_packets": 0,
  "groups": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}

Retrieves a list of devices

Returns all Devices for the authenticated account. Supports filtering, pagination, field selection, and sorting via query parameters.

Query Parameters

field_mask string

Selects which fields to include in the results. The specified field is included if present, along with the dev_eui field, which is always included. Provide an additional field_mask parameter for each additional field.

limit integer

Maximum number of elements to return per page. Optional. When omitted, all results are returned in a single response.

page integer

Page number of results to return. Optional. Default: 1.

order_by string

Sorts results by the specified field. Default: ascending alphabetical order. Prefix the value with a "-" to sort in descending order.

q string

{"$or":{"name":{"$ilike":"~temperature~"},"health_state":{"=":"good"}}}

Filters results by specific fields using a set of operators in a JSON-style format:

Operator	Notes
=	Returns all results that are an exact match
!=	Returns all results excluding those specified
$like	Returns all results that match a "~" wildcard search
$ilike	Returns all results that match a "~" case-insensitive wildcard search
$in	Returns all results that match the specified list
$nin	Returns all results excluding those in the specified list
$and	Returns all results that match all query parameters
$or	Returns all results that match any of the filter parameters
$intersects	Returns all results that match a group field value search

Body Parameters

No parameters.

Returns

× 200 Successful response containing the device list application/json

meta object

Pagination metadata for list responses.

records array of objects

List of Device records returned by the query.

× Hide array object attributes

name string

Human-readable name of the Device. Required. Must be unique within the account.

dev_eui string

Extended Unique Identifier (EUI-64) of the device. Required. Must be a 16-character hexadecimal string.

owner_id string

Identifies the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

activation_type enum (string)

Activation method used by the device. Required.

ABP: Activation By Personalization — device keys are hardcoded.
OTAA: Over-The-Air Activation — device keys are negotiated via a join procedure.

service_profile string

Unique identifier of the ServiceProfile assigned to the device. Required. Retrieve applicable values via GET /v1/serviceprofiles.

device_profile string

Unique identifier of the DeviceProfile assigned to the device. Required. Retrieve applicable values via GET /v1/deviceprofiles.

decoder_type string

Unique identifier of the Decoder used to decode packets from the device. Optional. Retrieve applicable values via GET /v1/decodertypes.

output_profile string

Unique identifier of the OutputProfile used for routing packets to external servers. Optional. Retrieve applicable values via GET /v1/outputprofiles.

private_data boolean

Whether device data is private. True means data is not stored; false means data is stored for future processing.

created_at string (date-time)

Timestamp of Device creation in RFC 3339 format.

updated_at string (date-time)

Timestamp of the last Device modification in RFC 3339 format.

updated_by string

Unique identifier of the User or Subscriber that last modified the Device.

last_uplink string (date-time)

Timestamp of the last uplink message from the Device in RFC 3339 format. Null if the device has never sent an uplink.

health_state enum (string)

Calculated health of the Device based on recent activity.

good: Device is performing well with strong signal quality.
fair: Device is operational but with degraded signal quality.
poor: Device is experiencing significant signal degradation.
offline: Device has not communicated recently.

spreading_factor integer

Current LoRa Spreading Factor of the device (e.g., 7 = SF7). Range: 7–12.

average_rssi float

Average Received Signal Strength Indicator (RSSI) over the last 24 hours, in dBm.

average_esp float

Average Estimated Signal Power (ESP) over the last 24 hours, in dBm.

average_snr float

Average Signal-to-Noise Ratio (SNR) over the last 24 hours, in dB.

packet_error_rate float

Percentage of dropped packets over the last 24 hours. Range: 0–100.

battery_level integer

Reported battery level from the Device. Null if the device does not report battery status.

average_weekly_packets integer

Average number of packets per day over the past week.

groups array of objects

List of Groups to which the Device belongs.

Query Parameters

GET /v2/devices

curl 'https://api.machineq.net/v2/devices'

Retrieves a device by DevEUI

Returns the Device identified by the given device EUI.

Path Parameters

dev_eui string required

Extended Unique Identifier of the device.

Body Parameters

No parameters.

Returns

× 200 Successful response containing the device application/json

name string

Human-readable name of the Device. Required. Must be unique within the account.

dev_eui string

Extended Unique Identifier (EUI-64) of the device. Required. Must be a 16-character hexadecimal string.

owner_id string

Identifies the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

activation_type enum (string)

Activation method used by the device. Required.

ABP: Activation By Personalization — device keys are hardcoded.
OTAA: Over-The-Air Activation — device keys are negotiated via a join procedure.

service_profile string

Unique identifier of the ServiceProfile assigned to the device. Required. Retrieve applicable values via GET /v1/serviceprofiles.

device_profile string

Unique identifier of the DeviceProfile assigned to the device. Required. Retrieve applicable values via GET /v1/deviceprofiles.

decoder_type string

Unique identifier of the Decoder used to decode packets from the device. Optional. Retrieve applicable values via GET /v1/decodertypes.

output_profile string

Unique identifier of the OutputProfile used for routing packets to external servers. Optional. Retrieve applicable values via GET /v1/outputprofiles.

private_data boolean

Whether device data is private. True means data is not stored; false means data is stored for future processing.

created_at string (date-time)

Timestamp of Device creation in RFC 3339 format.

updated_at string (date-time)

Timestamp of the last Device modification in RFC 3339 format.

updated_by string

Unique identifier of the User or Subscriber that last modified the Device.

last_uplink string (date-time)

Timestamp of the last uplink message from the Device in RFC 3339 format. Null if the device has never sent an uplink.

health_state enum (string)

Calculated health of the Device based on recent activity.

good: Device is performing well with strong signal quality.
fair: Device is operational but with degraded signal quality.
poor: Device is experiencing significant signal degradation.
offline: Device has not communicated recently.

spreading_factor integer

Current LoRa Spreading Factor of the device (e.g., 7 = SF7). Range: 7–12.

average_rssi float

Average Received Signal Strength Indicator (RSSI) over the last 24 hours, in dBm.

average_esp float

Average Estimated Signal Power (ESP) over the last 24 hours, in dBm.

average_snr float

Average Signal-to-Noise Ratio (SNR) over the last 24 hours, in dB.

packet_error_rate float

Percentage of dropped packets over the last 24 hours. Range: 0–100.

battery_level integer

Reported battery level from the Device. Null if the device does not report battery status.

average_weekly_packets integer

Average number of packets per day over the past week.

groups array of objects

List of Groups to which the Device belongs.

Path Parameters

GET /v2/devices/{dev_eui}

curl 'https://api.machineq.net/v2/devices/{dev_eui}'

Device Configuration

API for reading and managing device configurations.

Codec support

Not all devices support remote configuration — support depends on the device's codec. If the device's codec does not support config encoding, PUT will return 400. Use GET to check whether a device has ever had a desired config applied.

Rollout lifecycle

When a desired config is submitted via PUT, a rollout is created and the first fragment is dispatched asynchronously as a LoRaWAN downlink — typically within seconds, but callers should not assume immediate delivery. Subsequent fragments are sent one at a time after each preceding fragment is confirmed. The rollout moves through the following statuses:

Status	Description
`pending`	Briefly transitional — rollout accepted but first fragment not yet scheduled for transmission. Rarely visible in practice.
`in_progress`	First fragment scheduled for transmission; delivery underway
`applied`	All fragments confirmed
`failed`	A fragment failed after exhausting retries
`cancelled`	Cancelled via DELETE before completion

Fragment lifecycle

Each fragment within a rollout transitions independently:

Status	Description
`pending`	Not yet scheduled for transmission — either the rollout was just accepted or a prior fragment is still being confirmed
`ready`	Scheduled for the next transmission attempt
`queued`	Submitted to the network server
`sent`	Network server confirmed gateway transmission
`confirmed`	Device acknowledged (strategy-dependent)
`gateway_unavailable`	No connected gateway can reach the device; fragment is suspended and will resume automatically when device activity is observed
`failed`	Delivery failed after retry exhaustion
`cancelled`	Cancelled before confirmation

Confirmation strategies

The codec determines which strategy is used:

downlink-sent — fragment confirmed when the network server reports successful gateway transmission.
uplink-ack — fragment confirmed when the device sends a LoRaWAN acknowledged uplink in response to the downlink. Some device types additionally require the device to echo the configuration back in a specific response message before the fragment is considered confirmed.
reported-config — rollout applied when every parameter in the desired configuration is present in the device's reported configuration with the same value. The device may report additional parameters beyond those being set. Used for devices that report their configuration across multiple successive uplinks rather than in a single response. Only single-fragment rollouts are supported.

Endpoints

                GET/v2/devices/{dev_eui}/config
PUT/v2/devices/{dev_eui}/config/desired
DELETE/v2/devices/{dev_eui}/config/desired
GET/v2/devices/{dev_eui}/config/history

            

The Device Configuration object

Attributes

dev_eui string

Device EUI (uppercase).

reported object | null

Last configuration observed from a device uplink. null if the device has never sent a config uplink.

desired object | null

Most recent config rollout regardless of status. null if no rollout has ever been created for the device.

× Hide child attributes

config object

The desired configuration that was submitted.

source_type enum (string)

How this desired config was created.

manual: Submitted by a user via the API.

status enum (string)

Current lifecycle status of the rollout.

pending: Briefly transitional — rollout accepted but first fragment not yet scheduled for transmission.
in_progress: First fragment scheduled for transmission; delivery underway.
applied: All fragments confirmed.
failed: A fragment failed after exhausting retries.
cancelled: Cancelled via DELETE before completion.

failure_reason string | null

Human-readable failure description. Present only when status is failed.

created_by string

Identity that created the rollout.

updated_by string

Identity that last updated the rollout.

created_at string (date-time)

updated_at string (date-time)

started_at string | null

When the first fragment entered ready state (i.e. when the rollout transitioned to in_progress). null only while status is pending.

completed_at string | null

When the rollout reached a terminal state (applied, failed, or cancelled). null while the rollout is still active.

progress object

× Hide child attributes

total_fragments integer

Total number of downlink fragments in this rollout.

fragments_confirmed integer

Number of fragments that have been confirmed.

fragments array of objects

Per-fragment delivery state, ordered by sequence number.

× Hide array object attributes

sequence integer

1-based position of this fragment within the rollout.

status enum (string)

Current delivery status of this fragment.

pending: Not yet scheduled for transmission — either the rollout was just accepted or a prior fragment is still being confirmed.
ready: Scheduled for the next transmission attempt.
queued: Submitted to the network server.
sent: Network server confirmed gateway transmission.
confirmed: Device acknowledged (strategy-dependent).
failed: Delivery failed after retry exhaustion.
cancelled: Cancelled before confirmation.
gateway_unavailable: No connected gateway can reach the device; fragment is suspended and will resume automatically when device activity is observed.

attempt_count integer

Number of delivery attempts initiated for this fragment. Set to 1 when the fragment enters ready state (marking the start of the first ready→queued→sent cycle). Incremented on each retry. 0 only while the fragment is pending.

ready_at string | null

When this fragment most recently entered ready state. Reset on each retry, so it always reflects the start of the current ready→queued delivery cycle. null for pending fragments and for fragments created before this field was introduced.

queued_at string | null

When the fragment was submitted to the network server. null until queued.

sent_at string | null

Gateway transmission timestamp reported by the network server. null until sent. This is the network server's clock, not the API server's.

confirmed_at string | null

When this fragment was confirmed (strategy-dependent). null until confirmed.

gateway_unavailable_at string | null

When this fragment entered gateway_unavailable state. Non-null only while the fragment is suspended waiting for device activity to resume. Cleared when the fragment returns to ready.

The Device Configuration object

{
  "dev_eui": "string",
  "reported": {
    "config": {},
    "last_uplink_at": "2006-01-02T15:04:05.000Z"
  },
  "desired": {
    "config": {},
    "source_type": "string",
    "status": "string",
    "failure_reason": "string",
    "created_by": "string",
    "updated_by": "string",
    "created_at": "2006-01-02T15:04:05.000Z",
    "updated_at": "2006-01-02T15:04:05.000Z",
    "started_at": "string",
    "completed_at": "string",
    "progress": {
      "total_fragments": 0,
      "fragments_confirmed": 0,
      "fragments": [
        {
          "sequence": 0,
          "status": "string",
          "attempt_count": 0,
          "ready_at": "string",
          "queued_at": "string",
          "sent_at": "string",
          "confirmed_at": "string",
          "gateway_unavailable_at": "string"
        }
      ]
    }
  }
}

Get device configuration

Returns the reported and desired configuration for a device.

reported reflects the last configuration observed from a device uplink. null if the device has never sent a config uplink.
desired reflects the most recent config rollout, including terminal rollouts (applied, failed, cancelled). null if no rollout has ever been created for the device.

Path Parameters

dev_eui string required

Device EUI — exactly 16 hexadecimal characters (case-insensitive). Internally normalized to uppercase.

Body Parameters

No parameters.

Returns

× 200 Device configuration retrieved successfully application/json

{
  "desired": null,
  "dev_eui": "AABB1122CCDD3344",
  "reported": null
}

{
  "desired": {
    "config": {
      "report_interval_seconds": 60,
      "threshold_celsius": 30
    },
    "created_at": "2026-04-20T09:00:00Z",
    "created_by": "Job3ZjzC",
    "progress": {
      "fragments": [
        {
          "attempt_count": 1,
          "confirmed_at": "2026-04-20T09:00:08Z",
          "queued_at": "2026-04-20T09:00:05Z",
          "sent_at": "2026-04-20T09:00:06Z",
          "sequence": 1,
          "status": "confirmed"
        },
        {
          "attempt_count": 1,
          "queued_at": "2026-04-20T09:00:09Z",
          "sent_at": "2026-04-20T09:00:10Z",
          "sequence": 2,
          "status": "sent"
        }
      ],
      "fragments_confirmed": 1,
      "total_fragments": 2
    },
    "source_type": "manual",
    "started_at": "2026-04-20T09:00:05Z",
    "status": "in_progress",
    "updated_at": "2026-04-20T09:00:05Z",
    "updated_by": "Job3ZjzC"
  },
  "dev_eui": "AABB1122CCDD3344",
  "reported": {
    "config": {
      "report_interval_seconds": 300,
      "threshold_celsius": 25
    },
    "last_uplink_at": "2026-04-18T10:00:00Z"
  }
}

{
  "desired": null,
  "dev_eui": "AABB1122CCDD3344",
  "reported": {
    "config": {
      "report_interval_seconds": 300
    },
    "last_uplink_at": "2026-04-18T10:00:00Z"
  }
}

{
  "desired": {
    "completed_at": "2026-04-20T09:05:00Z",
    "config": {
      "report_interval_seconds": 60
    },
    "created_at": "2026-04-20T09:00:00Z",
    "created_by": "Job3ZjzC",
    "failure_reason": "downlink delivery failed: tx error",
    "progress": {
      "fragments": [
        {
          "attempt_count": 3,
          "queued_at": "2026-04-20T09:00:05Z",
          "sent_at": "2026-04-20T09:00:06Z",
          "sequence": 1,
          "status": "failed"
        }
      ],
      "fragments_confirmed": 0,
      "total_fragments": 1
    },
    "source_type": "manual",
    "started_at": "2026-04-20T09:00:05Z",
    "status": "failed",
    "updated_at": "2026-04-20T09:05:00Z",
    "updated_by": "admin"
  },
  "dev_eui": "AABB1122CCDD3344",
  "reported": {
    "config": {
      "report_interval_seconds": 300
    },
    "last_uplink_at": "2026-04-18T10:00:00Z"
  }
}

{
  "desired": {
    "completed_at": "2026-04-20T09:01:00Z",
    "config": {
      "report_interval_seconds": 60,
      "threshold_celsius": 30
    },
    "created_at": "2026-04-20T09:00:00Z",
    "created_by": "Job3ZjzC",
    "progress": {
      "fragments": [
        {
          "attempt_count": 1,
          "confirmed_at": "2026-04-20T09:01:00Z",
          "queued_at": "2026-04-20T09:00:05Z",
          "sent_at": "2026-04-20T09:00:06Z",
          "sequence": 1,
          "status": "confirmed"
        }
      ],
      "fragments_confirmed": 1,
      "total_fragments": 1
    },
    "source_type": "manual",
    "started_at": "2026-04-20T09:00:05Z",
    "status": "applied",
    "updated_at": "2026-04-20T09:01:00Z",
    "updated_by": "Job3ZjzC"
  },
  "dev_eui": "AABB1122CCDD3344",
  "reported": {
    "config": {
      "report_interval_seconds": 60,
      "threshold_celsius": 30
    },
    "last_uplink_at": "2026-04-20T09:01:00Z"
  }
}

dev_eui string

Device EUI (uppercase).

reported object | null

Last configuration observed from a device uplink. null if the device has never sent a config uplink.

desired object | null

Most recent config rollout regardless of status. null if no rollout has ever been created for the device.

× Hide child attributes

config object

The desired configuration that was submitted.

source_type enum (string)

How this desired config was created.

manual: Submitted by a user via the API.

status enum (string)

Current lifecycle status of the rollout.

pending: Briefly transitional — rollout accepted but first fragment not yet scheduled for transmission.
in_progress: First fragment scheduled for transmission; delivery underway.
applied: All fragments confirmed.
failed: A fragment failed after exhausting retries.
cancelled: Cancelled via DELETE before completion.

failure_reason string | null

Human-readable failure description. Present only when status is failed.

created_by string

Identity that created the rollout.

updated_by string

Identity that last updated the rollout.

created_at string (date-time)

updated_at string (date-time)

started_at string | null

When the first fragment entered ready state (i.e. when the rollout transitioned to in_progress). null only while status is pending.

completed_at string | null

When the rollout reached a terminal state (applied, failed, or cancelled). null while the rollout is still active.

progress object

× Hide child attributes

total_fragments integer

Total number of downlink fragments in this rollout.

fragments_confirmed integer

Number of fragments that have been confirmed.

fragments array of objects

Per-fragment delivery state, ordered by sequence number.

× Hide array object attributes

sequence integer

1-based position of this fragment within the rollout.

status enum (string)

Current delivery status of this fragment.

pending: Not yet scheduled for transmission — either the rollout was just accepted or a prior fragment is still being confirmed.
ready: Scheduled for the next transmission attempt.
queued: Submitted to the network server.
sent: Network server confirmed gateway transmission.
confirmed: Device acknowledged (strategy-dependent).
failed: Delivery failed after retry exhaustion.
cancelled: Cancelled before confirmation.
gateway_unavailable: No connected gateway can reach the device; fragment is suspended and will resume automatically when device activity is observed.

attempt_count integer

Number of delivery attempts initiated for this fragment. Set to 1 when the fragment enters ready state (marking the start of the first ready→queued→sent cycle). Incremented on each retry. 0 only while the fragment is pending.

ready_at string | null

When this fragment most recently entered ready state. Reset on each retry, so it always reflects the start of the current ready→queued delivery cycle. null for pending fragments and for fragments created before this field was introduced.

queued_at string | null

When the fragment was submitted to the network server. null until queued.

sent_at string | null

Gateway transmission timestamp reported by the network server. null until sent. This is the network server's clock, not the API server's.

confirmed_at string | null

When this fragment was confirmed (strategy-dependent). null until confirmed.

gateway_unavailable_at string | null

When this fragment entered gateway_unavailable state. Non-null only while the fragment is suspended waiting for device activity to resume. Cleared when the fragment returns to ready.

Path Parameters

GET /v2/devices/{dev_eui}/config

curl 'https://api.machineq.net/v2/devices/{dev_eui}/config'

Set desired device configuration

Submits a desired configuration for the device. If an active rollout already exists it is cancelled and replaced with the new one. The first fragment is dispatched asynchronously; subsequent fragments follow as each is confirmed.

The config object must be valid for the device's codec type. The codec determines how the config is encoded into downlink fragments and which confirmation strategy is used. Returns 400 if the codec does not support device config encoding or if the config fails validation.

Returns 204 No Content when the desired config is already fully reflected in the device's reported config — no rollout is created in this case.

Returns 202 Accepted when a rollout is created. Fragment delivery is asynchronous; poll GET /devices/{dev_eui}/config to track progress.

Path Parameters

dev_eui string required

Device EUI — exactly 16 hexadecimal characters (case-insensitive). Internally normalized to uppercase.

Body Parameters

config object required

Desired device configuration. The structure is codec-specific — the device's codec type determines how this object is validated and encoded into downlink fragments.

Examples

Returns

× 202 Desired config accepted and a rollout created with the first fragment ready for dispatch application/json

{
  "config": {
    "report_interval_seconds": 60,
    "threshold_celsius": 30
  },
  "created_at": "2026-04-20T09:00:00Z",
  "created_by": "Job3ZjzC",
  "progress": {
    "fragments": [
      {
        "attempt_count": 1,
        "sequence": 1,
        "status": "ready"
      },
      {
        "attempt_count": 0,
        "sequence": 2,
        "status": "pending"
      }
    ],
    "fragments_confirmed": 0,
    "total_fragments": 2
  },
  "source_type": "manual",
  "started_at": "2026-04-20T09:00:00Z",
  "status": "in_progress",
  "updated_at": "2026-04-20T09:00:00Z",
  "updated_by": "Job3ZjzC"
}

config object

The desired configuration that was submitted.

source_type enum (string)

How this desired config was created.

manual: Submitted by a user via the API.

status enum (string)

Current lifecycle status of the rollout.

pending: Briefly transitional — rollout accepted but first fragment not yet scheduled for transmission.
in_progress: First fragment scheduled for transmission; delivery underway.
applied: All fragments confirmed.
failed: A fragment failed after exhausting retries.
cancelled: Cancelled via DELETE before completion.

failure_reason string | null

Human-readable failure description. Present only when status is failed.

created_by string

Identity that created the rollout.

updated_by string

Identity that last updated the rollout.

created_at string (date-time)

updated_at string (date-time)

started_at string | null

When the first fragment entered ready state (i.e. when the rollout transitioned to in_progress). null only while status is pending.

completed_at string | null

When the rollout reached a terminal state (applied, failed, or cancelled). null while the rollout is still active.

progress object

× Hide child attributes

total_fragments integer

Total number of downlink fragments in this rollout.

fragments_confirmed integer

Number of fragments that have been confirmed.

fragments array of objects

Per-fragment delivery state, ordered by sequence number.

× Hide array object attributes

sequence integer

1-based position of this fragment within the rollout.

status enum (string)

Current delivery status of this fragment.

pending: Not yet scheduled for transmission — either the rollout was just accepted or a prior fragment is still being confirmed.
ready: Scheduled for the next transmission attempt.
queued: Submitted to the network server.
sent: Network server confirmed gateway transmission.
confirmed: Device acknowledged (strategy-dependent).
failed: Delivery failed after retry exhaustion.
cancelled: Cancelled before confirmation.
gateway_unavailable: No connected gateway can reach the device; fragment is suspended and will resume automatically when device activity is observed.

attempt_count integer

Number of delivery attempts initiated for this fragment. Set to 1 when the fragment enters ready state (marking the start of the first ready→queued→sent cycle). Incremented on each retry. 0 only while the fragment is pending.

ready_at string | null

When this fragment most recently entered ready state. Reset on each retry, so it always reflects the start of the current ready→queued delivery cycle. null for pending fragments and for fragments created before this field was introduced.

queued_at string | null

When the fragment was submitted to the network server. null until queued.

sent_at string | null

Gateway transmission timestamp reported by the network server. null until sent. This is the network server's clock, not the API server's.

confirmed_at string | null

When this fragment was confirmed (strategy-dependent). null until confirmed.

gateway_unavailable_at string | null

When this fragment entered gateway_unavailable state. Non-null only while the fragment is suspended waiting for device activity to resume. Cleared when the fragment returns to ready.

Path Parameters

Body

{
  "config": {}
}

PUT /v2/devices/{dev_eui}/config/desired

curl -X PUT 'https://api.machineq.net/v2/devices/{dev_eui}/config/desired'

Cancel desired device configuration

Cancels the active rollout for the device. Any in-flight fragment is also cancelled. If no active rollout exists the response is 204 No Content.

Note that cancellation only affects the rollout state — any fragments already delivered to the device are not reversed.

Path Parameters

dev_eui string required

Device EUI — exactly 16 hexadecimal characters (case-insensitive). Internally normalized to uppercase.

Body Parameters

No parameters.

Returns

× 200 Active rollout found and cancelled application/json

{
  "config": {
    "report_interval_seconds": 60,
    "threshold_celsius": 30
  },
  "created_at": "2026-04-20T09:00:00Z",
  "created_by": "Job3ZjzC",
  "progress": {
    "fragments": [
      {
        "attempt_count": 1,
        "confirmed_at": "2026-04-20T09:01:00Z",
        "queued_at": "2026-04-20T09:00:05Z",
        "sent_at": "2026-04-20T09:00:06Z",
        "sequence": 1,
        "status": "confirmed"
      },
      {
        "attempt_count": 1,
        "queued_at": "2026-04-20T09:01:01Z",
        "sequence": 2,
        "status": "cancelled"
      }
    ],
    "fragments_confirmed": 1,
    "total_fragments": 2
  },
  "source_type": "manual",
  "started_at": "2026-04-20T09:00:05Z",
  "status": "cancelled",
  "updated_at": "2026-04-20T09:02:00Z",
  "updated_by": "Job3ZjzC"
}

config object

The desired configuration that was submitted.

source_type enum (string)

How this desired config was created.

manual: Submitted by a user via the API.

status enum (string)

Current lifecycle status of the rollout.

pending: Briefly transitional — rollout accepted but first fragment not yet scheduled for transmission.
in_progress: First fragment scheduled for transmission; delivery underway.
applied: All fragments confirmed.
failed: A fragment failed after exhausting retries.
cancelled: Cancelled via DELETE before completion.

failure_reason string | null

Human-readable failure description. Present only when status is failed.

created_by string

Identity that created the rollout.

updated_by string

Identity that last updated the rollout.

created_at string (date-time)

updated_at string (date-time)

started_at string | null

When the first fragment entered ready state (i.e. when the rollout transitioned to in_progress). null only while status is pending.

completed_at string | null

When the rollout reached a terminal state (applied, failed, or cancelled). null while the rollout is still active.

progress object

× Hide child attributes

total_fragments integer

Total number of downlink fragments in this rollout.

fragments_confirmed integer

Number of fragments that have been confirmed.

fragments array of objects

Per-fragment delivery state, ordered by sequence number.

× Hide array object attributes

sequence integer

1-based position of this fragment within the rollout.

status enum (string)

Current delivery status of this fragment.

pending: Not yet scheduled for transmission — either the rollout was just accepted or a prior fragment is still being confirmed.
ready: Scheduled for the next transmission attempt.
queued: Submitted to the network server.
sent: Network server confirmed gateway transmission.
confirmed: Device acknowledged (strategy-dependent).
failed: Delivery failed after retry exhaustion.
cancelled: Cancelled before confirmation.
gateway_unavailable: No connected gateway can reach the device; fragment is suspended and will resume automatically when device activity is observed.

attempt_count integer

Number of delivery attempts initiated for this fragment. Set to 1 when the fragment enters ready state (marking the start of the first ready→queued→sent cycle). Incremented on each retry. 0 only while the fragment is pending.

ready_at string | null

When this fragment most recently entered ready state. Reset on each retry, so it always reflects the start of the current ready→queued delivery cycle. null for pending fragments and for fragments created before this field was introduced.

queued_at string | null

When the fragment was submitted to the network server. null until queued.

sent_at string | null

Gateway transmission timestamp reported by the network server. null until sent. This is the network server's clock, not the API server's.

confirmed_at string | null

When this fragment was confirmed (strategy-dependent). null until confirmed.

gateway_unavailable_at string | null

When this fragment entered gateway_unavailable state. Non-null only while the fragment is suspended waiting for device activity to resume. Cleared when the fragment returns to ready.

Path Parameters

DELETE /v2/devices/{dev_eui}/config/desired

curl -X DELETE 'https://api.machineq.net/v2/devices/{dev_eui}/config/desired'

Get device reported config history

Returns a paginated log of reported configuration changes for a device, ordered most-recent first. Each record represents a moment when the device's reported config changed to a new value, as detected from an uplink.

The log is capped per device. Use page_token to paginate through older records. limit defaults to 20; large values are clamped to a server-side maximum. The meta.more field is always present and explicitly indicates whether a further page exists.

Path Parameters

dev_eui string required

Device EUI — exactly 16 hexadecimal characters (case-insensitive). Internally normalized to uppercase.

Query Parameters

limit integer

Maximum number of records to return. Defaults to 20 when omitted. Large values are clamped to a server-side maximum.

page_token string

Opaque pagination cursor from meta.next_page_token in the previous response. Omit to request the first page.

Body Parameters

No parameters.

Returns

× 200 Config history retrieved successfully application/json

{
  "meta": {
    "more": true,
    "next_page_token": "MjAyNi0wNS0yMFQxNDozMjowMC4xMjM0NTZa"
  },
  "records": [
    {
      "config": {
        "report_interval_seconds": 60,
        "threshold_celsius": 30
      },
      "observed_at": "2026-05-20T14:32:00.123456Z"
    },
    {
      "config": {
        "report_interval_seconds": 300,
        "threshold_celsius": 25
      },
      "observed_at": "2026-05-19T08:00:00.000000Z"
    }
  ]
}

{
  "meta": {
    "more": false
  },
  "records": [
    {
      "config": {
        "report_interval_seconds": 300,
        "threshold_celsius": 25
      },
      "observed_at": "2026-04-01T12:00:00.000000Z"
    }
  ]
}

{
  "meta": {
    "more": false
  },
  "records": []
}

records array of objects

History entries ordered most-recent first.

meta object

Path Parameters

Query Parameters

GET /v2/devices/{dev_eui}/config/history

curl 'https://api.machineq.net/v2/devices/{dev_eui}/config/history'

Output Destinations

Output Destinations define the client-side collector of data emitted from the MQcentral platform.

Most Output Destinations require credentials so that the MachineQ output system can establish an authenticated connection. An Output Credentials association varies depending on the type of Output Destination:

webhook Output Destinations typically use basic_auth or client_credentials credentials.
mqtt Output Destinations typically use basic_auth credentials.
aws_iot_core Output Destinations use x509_certificate credentials.
azure_iot_hub Output Destinations use azure_shared_access_policy credentials.

Endpoints

                GET/v2/output/destinations
POST/v2/output/destinations
GET/v2/output/destinations/{destination_id}
PUT/v2/output/destinations/{destination_id}
DELETE/v2/output/destinations/{destination_id}

            

The Output Destinations object

Attributes

id string

Unique identifier of the resource.

owner_id string

Unique identifier of the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

name string

Human-readable name of the Destination. Required.

type enum (string)

Type of the Destination. Required.

webhook: Delivers events via HTTP POST to a URL.
azure_iot_hub: Delivers events to an Azure IoT Hub.
mqtt: Delivers events to an MQTT broker.
aws_iot_core: Delivers events to AWS IoT Core.

enabled boolean

Whether Output Events are delivered to the Destination. True means events are delivered; false means delivery is paused. Optional.

credentials_id string

Unique identifier of the Credentials used to authenticate delivery. Optional.

data object

Type-specific destination configuration details. Required.

One of:

The Output Destinations object

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "url": "string",
    "headers": [
      {
        "header": "string",
        "value": "string"
      }
    ]
  }
}

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "host": "string"
  }
}

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "host": "string",
    "topic": "string",
    "tls_enabled": true,
    "custom_client_id": "string"
  }
}

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "endpoint": "string"
  }
}

Retrieves a list of output destinations

Returns all Output Destinations for the authenticated account.

Body Parameters

No parameters.

Returns

× 200 Successful response containing the output destination list application/json

meta object

records array of objects

List of Output Destination records.

× Hide array object attributes

id string

Unique identifier of the resource.

owner_id string

Unique identifier of the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

name string

Human-readable name of the Destination. Required.

type enum (string)

Type of the Destination. Required.

webhook: Delivers events via HTTP POST to a URL.
azure_iot_hub: Delivers events to an Azure IoT Hub.
mqtt: Delivers events to an MQTT broker.
aws_iot_core: Delivers events to AWS IoT Core.

enabled boolean

Whether Output Events are delivered to the Destination. True means events are delivered; false means delivery is paused. Optional.

credentials_id string

Unique identifier of the Credentials used to authenticate delivery. Optional.

data object

Type-specific destination configuration details. Required.

One of:

GET /v2/output/destinations

curl 'https://api.machineq.net/v2/output/destinations'

Creates a new output destination

Creates a new Output Destination with the given configuration.

Body Parameters

name string required

Human-readable name of the Destination. Required.

type enum (string) required

Type of the Destination. Required.

webhook: Delivers events via HTTP POST to a URL.
azure_iot_hub: Delivers events to an Azure IoT Hub.
mqtt: Delivers events to an MQTT broker.
aws_iot_core: Delivers events to AWS IoT Core.

enabled boolean

Whether Output Events are delivered to the Destination. True means events are delivered; false means delivery is paused. Optional.

credentials_id string

Unique identifier of the Credentials used to authenticate delivery. Optional.

data object required

Type-specific destination configuration details. Required.

One of:

Examples

Returns

× 201 Output destination created successfully application/json

id string

Unique identifier of the resource.

owner_id string

Unique identifier of the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

name string

Human-readable name of the Destination. Required.

type enum (string)

Type of the Destination. Required.

webhook: Delivers events via HTTP POST to a URL.
azure_iot_hub: Delivers events to an Azure IoT Hub.
mqtt: Delivers events to an MQTT broker.
aws_iot_core: Delivers events to AWS IoT Core.

enabled boolean

Whether Output Events are delivered to the Destination. True means events are delivered; false means delivery is paused. Optional.

credentials_id string

Unique identifier of the Credentials used to authenticate delivery. Optional.

data object

Type-specific destination configuration details. Required.

One of:

Body

{
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "url": "string",
    "headers": [
      {
        "header": "string",
        "value": "string"
      }
    ]
  }
}

{
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "host": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "host": "string",
    "topic": "string",
    "tls_enabled": true,
    "custom_client_id": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "endpoint": "string"
  }
}

POST /v2/output/destinations

curl -X POST 'https://api.machineq.net/v2/output/destinations'

Retrieves an output destination by ID

Returns the Output Destination identified by the given destination_id.

Path Parameters

destination_id string required

Unique identifier of the Output Destination.

Body Parameters

No parameters.

Returns

× 200 Successful response containing the output destination application/json

id string

Unique identifier of the resource.

owner_id string

Unique identifier of the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

name string

Human-readable name of the Destination. Required.

type enum (string)

Type of the Destination. Required.

webhook: Delivers events via HTTP POST to a URL.
azure_iot_hub: Delivers events to an Azure IoT Hub.
mqtt: Delivers events to an MQTT broker.
aws_iot_core: Delivers events to AWS IoT Core.

enabled boolean

Whether Output Events are delivered to the Destination. True means events are delivered; false means delivery is paused. Optional.

credentials_id string

Unique identifier of the Credentials used to authenticate delivery. Optional.

data object

Type-specific destination configuration details. Required.

One of:

Path Parameters

GET /v2/output/destinations/{destination_id}

curl 'https://api.machineq.net/v2/output/destinations/{destination_id}'

Updates an output destination by ID

Replaces the Output Destination identified by the given destination_id with the provided configuration.

Path Parameters

destination_id string required

Unique identifier of the Output Destination.

Body Parameters

name string required

Human-readable name of the Destination. Required.

type enum (string) required

Type of the Destination. Required.

webhook: Delivers events via HTTP POST to a URL.
azure_iot_hub: Delivers events to an Azure IoT Hub.
mqtt: Delivers events to an MQTT broker.
aws_iot_core: Delivers events to AWS IoT Core.

enabled boolean

Whether Output Events are delivered to the Destination. True means events are delivered; false means delivery is paused. Optional.

credentials_id string

Unique identifier of the Credentials used to authenticate delivery. Optional.

data object required

Type-specific destination configuration details. Required.

One of:

Returns

× 200 Successful response containing the updated output destination application/json

id string

Unique identifier of the resource.

owner_id string

Unique identifier of the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

name string

Human-readable name of the Destination. Required.

type enum (string)

Type of the Destination. Required.

webhook: Delivers events via HTTP POST to a URL.
azure_iot_hub: Delivers events to an Azure IoT Hub.
mqtt: Delivers events to an MQTT broker.
aws_iot_core: Delivers events to AWS IoT Core.

enabled boolean

Whether Output Events are delivered to the Destination. True means events are delivered; false means delivery is paused. Optional.

credentials_id string

Unique identifier of the Credentials used to authenticate delivery. Optional.

data object

Type-specific destination configuration details. Required.

One of:

Path Parameters

Body

{
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "url": "string",
    "headers": [
      {
        "header": "string",
        "value": "string"
      }
    ]
  }
}

{
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "host": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "host": "string",
    "topic": "string",
    "tls_enabled": true,
    "custom_client_id": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "enabled": true,
  "credentials_id": "string",
  "data": {
    "endpoint": "string"
  }
}

PUT /v2/output/destinations/{destination_id}

curl -X PUT 'https://api.machineq.net/v2/output/destinations/{destination_id}'

Deletes an output destination by ID

Deletes the Output Destination identified by the given destination_id. This operation is irreversible.

Important: Deleting an Output Destination also removes it from all associated Output Alerts without warning. This may leave one or more Output Alerts with zero associated Output Destinations.

Deleting an Output Destination does not remove the associated Output Credentials.

Path Parameters

destination_id string required

Unique identifier of the Output Destination.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v2/output/destinations/{destination_id}

curl -X DELETE 'https://api.machineq.net/v2/output/destinations/{destination_id}'

Output Alerts

Output Alerts define the relationship between data produced by physical IoT infrastructure and the rules that govern an alert condition.

Endpoints

                GET/v2/output/alerts
POST/v2/output/alerts
GET/v2/output/alerts/{alert_id}
PUT/v2/output/alerts/{alert_id}
DELETE/v2/output/alerts/{alert_id}
POST/v2/output/alerts/{alert_id}/gateways:add
POST/v2/output/alerts/{alert_id}/gateways:remove
POST/v2/output/alerts/{alert_id}/gateways:batch_add
POST/v2/output/alerts/{alert_id}/gateways:batch_remove

            

The Output Alerts object

Attributes

id string

Unique identifier of the resource.

owner_id string

Unique identifier of the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

name string

Human-readable name of the Alert. Required.

type enum (string)

Type of the Alert. Required.

gateway_connectivity: Triggers when a gateway connectivity status changes.

data object

One of:

destination_ids array of strings

List of unique identifiers of the Destinations to which alert events are delivered. Required. Minimum 1 item.

The Output Alerts object

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "data": {
    "node_ids": [
      "string"
    ]
  },
  "destination_ids": [
    "string"
  ]
}

Retrieves a list of output alerts

Returns all Output Alerts for the authenticated account.

Body Parameters

No parameters.

Returns

GET /v2/output/alerts

curl 'https://api.machineq.net/v2/output/alerts'

Creates a new output alert

Creates a new Output Alert with the given configuration.

Body Parameters

name string required

Human-readable name of the Alert. Required.

type enum (string) required

Type of the Alert. Required.

gateway_connectivity: Triggers when a gateway connectivity status changes.

data object

One of:

destination_ids array of strings required

List of unique identifiers of the Destinations to which alert events are delivered. Required. Minimum 1 item.

Examples

Returns

Body

{
  "name": "string",
  "type": "string",
  "data": {
    "node_ids": [
      "string"
    ]
  },
  "destination_ids": [
    "string"
  ]
}

POST /v2/output/alerts

curl -X POST 'https://api.machineq.net/v2/output/alerts'

Retrieves an output alert by ID

Returns the Output Alert identified by the given alert_id.

Path Parameters

alert_id string required

Unique identifier of the Output Alert.

Body Parameters

No parameters.

Returns

Path Parameters

GET /v2/output/alerts/{alert_id}

curl 'https://api.machineq.net/v2/output/alerts/{alert_id}'

Updates an output alert by ID

Replaces the Output Alert identified by the given alert_id with the provided configuration.

Path Parameters

alert_id string required

Unique identifier of the Output Alert.

Body Parameters

name string required

Human-readable name of the Alert. Required.

type enum (string) required

Type of the Alert. Required.

gateway_connectivity: Triggers when a gateway connectivity status changes.

data object

One of:

destination_ids array of strings required

List of unique identifiers of the Destinations to which alert events are delivered. Required. Minimum 1 item.

Examples

Returns

Path Parameters

Body

{
  "name": "string",
  "type": "string",
  "data": {
    "node_ids": [
      "string"
    ]
  },
  "destination_ids": [
    "string"
  ]
}

PUT /v2/output/alerts/{alert_id}

curl -X PUT 'https://api.machineq.net/v2/output/alerts/{alert_id}'

Deletes an output alert by ID

Deletes the Output Alert identified by the given alert_id. This operation is irreversible.

Deleting an Output Alert does not remove the associated Output Destinations.

Path Parameters

alert_id string required

Unique identifier of the Output Alert.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v2/output/alerts/{alert_id}

curl -X DELETE 'https://api.machineq.net/v2/output/alerts/{alert_id}'

Adds a gateway to an output alert

Adds the Gateway identified by the given node_id to the Output Alert identified by the given alert_id if it does not already exist.

Returns an HTTP 409 Conflict error if the given node_id is already associated to the Output Alert.

Path Parameters

alert_id string required

Unique identifier of the Output Alert.

Body Parameters

node_id string required

Unique node_id of the Gateway to add. Required.

Examples

Returns

Path Parameters

Body

{
  "node_id": "string"
}

POST /v2/output/alerts/{alert_id}/gateways:add

curl -X POST 'https://api.machineq.net/v2/output/alerts/{alert_id}/gateways:add'

Removes a gateway from an output alert

Removes the Gateway identified by the given node_id from the Output Alert identified by the given alert_id if it exists.

Returns an HTTP 412 Precondition Failed error if the given node_id is not currently associated to the Output Alert.

Path Parameters

alert_id string required

Unique identifier of the Output Alert.

Body Parameters

node_id string required

Unique node_id of the Gateway to remove. Required.

Examples

Returns

Path Parameters

Body

{
  "node_id": "string"
}

POST /v2/output/alerts/{alert_id}/gateways:remove

curl -X POST 'https://api.machineq.net/v2/output/alerts/{alert_id}/gateways:remove'

Adds a batch of gateways to an output alert

Adds all Gateways in the given collection of node_ids to the Output Alert identified by the given alert_id if they do not already exist.

The entire batch fails with an HTTP 409 Conflict error if any of the given node_ids are already associated to the Output Alert.

Path Parameters

alert_id string required

Unique identifier of the Output Alert.

Body Parameters

node_ids array of strings required

List of gateway node_id values to add. Required. Minimum 1 item.

Examples

Returns

Path Parameters

Body

{
  "node_ids": [
    "string"
  ]
}

POST /v2/output/alerts/{alert_id}/gateways:batch_add

curl -X POST 'https://api.machineq.net/v2/output/alerts/{alert_id}/gateways:batch_add'

Removes a batch of gateways from an output alert

Removes all Gateways in the given collection of node_ids from the Output Alert identified by the given alert_id if they exist.

The entire batch fails with an HTTP 412 Precondition Failed error if any of the given node_ids are not currently associated to the Output Alert.

Path Parameters

alert_id string required

Unique identifier of the Output Alert.

Body Parameters

node_ids array of strings required

List of gateway node_id values to remove. Required. Minimum 1 item.

Examples

Returns

Path Parameters

Body

{
  "node_ids": [
    "string"
  ]
}

POST /v2/output/alerts/{alert_id}/gateways:batch_remove

curl -X POST 'https://api.machineq.net/v2/output/alerts/{alert_id}/gateways:batch_remove'

Output Credentials

Output Credentials specify the access criteria used when delivering data to Output Destinations.

Endpoints

                GET/v2/output/credentials
POST/v2/output/credentials
GET/v2/output/credentials/{credentials_id}
PUT/v2/output/credentials/{credentials_id}
DELETE/v2/output/credentials/{credentials_id}

            

The Output Credentials object

Attributes

id string

Unique identifier of the resource.

owner_id string

Unique identifier of the owner of the resource. Resources are isolated to their owner and are not visible across ownership boundaries.

name string

Human-readable name of the Credentials. Required.

type enum (string)

Type of the Credentials. Required.

basic_auth: Username and password authentication.
client_credentials: OAuth 2.0 client credentials grant.
x509_certificate: X.509 certificate-based authentication.
azure_shared_access_policy: Azure IoT Hub Shared Access Policy authentication.

data object

Type-specific credential details. Required.

One of:

The Output Credentials object

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "data": {
    "username": "string",
    "password": "string"
  }
}

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "data": {
    "client_id": "string",
    "client_secret": "string",
    "auth_url": "string",
    "scopes": "string",
    "audience": "string"
  }
}

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "data": {
    "public_key": "string",
    "private_key": "string"
  }
}

{
  "id": "string",
  "owner_id": "string",
  "name": "string",
  "type": "string",
  "data": {
    "policy_name": "string",
    "shared_access_key": "string"
  }
}

Retrieves a list of output credentials

Returns all Output Credentials for the authenticated account. Sensitive fields are redacted from the response.

Body Parameters

No parameters.

Returns

GET /v2/output/credentials

curl 'https://api.machineq.net/v2/output/credentials'

Creates new output credentials

Creates new Output Credentials with the given configuration. Secrets are written to an encrypted store and never persisted in plain text.

Body Parameters

name string required

Human-readable name of the Credentials. Required.

type enum (string) required

Type of the Credentials. Required.

basic_auth: Username and password authentication.
client_credentials: OAuth 2.0 client credentials grant.
x509_certificate: X.509 certificate-based authentication.
azure_shared_access_policy: Azure IoT Hub Shared Access Policy authentication.

data object required

Type-specific credential details. Required.

One of:

Examples

Returns

Body

{
  "name": "string",
  "type": "string",
  "data": {
    "username": "string",
    "password": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "data": {
    "client_id": "string",
    "client_secret": "string",
    "auth_url": "string",
    "scopes": "string",
    "audience": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "data": {
    "public_key": "string",
    "private_key": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "data": {
    "policy_name": "string",
    "shared_access_key": "string"
  }
}

POST /v2/output/credentials

curl -X POST 'https://api.machineq.net/v2/output/credentials'

Retrieves output credentials by ID

Returns the Output Credentials identified by the given credentials_id. Sensitive fields are redacted from the response.

Path Parameters

credentials_id string required

Unique identifier of the Output Credentials.

Body Parameters

No parameters.

Returns

Path Parameters

GET /v2/output/credentials/{credentials_id}

curl 'https://api.machineq.net/v2/output/credentials/{credentials_id}'

Updates output credentials by ID

Replaces the Output Credentials identified by the given credentials_id with the provided configuration.

Path Parameters

credentials_id string required

Unique identifier of the Output Credentials.

Body Parameters

name string required

Human-readable name of the Credentials. Required.

type enum (string) required

Type of the Credentials. Required.

basic_auth: Username and password authentication.
client_credentials: OAuth 2.0 client credentials grant.
x509_certificate: X.509 certificate-based authentication.
azure_shared_access_policy: Azure IoT Hub Shared Access Policy authentication.

data object required

Type-specific credential details. Required.

One of:

Examples

Returns

Path Parameters

Body

{
  "name": "string",
  "type": "string",
  "data": {
    "username": "string",
    "password": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "data": {
    "client_id": "string",
    "client_secret": "string",
    "auth_url": "string",
    "scopes": "string",
    "audience": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "data": {
    "public_key": "string",
    "private_key": "string"
  }
}

{
  "name": "string",
  "type": "string",
  "data": {
    "policy_name": "string",
    "shared_access_key": "string"
  }
}

PUT /v2/output/credentials/{credentials_id}

curl -X PUT 'https://api.machineq.net/v2/output/credentials/{credentials_id}'

Deletes output credentials by ID

Deletes the Output Credentials identified by the given credentials_id. This operation is irreversible.

Important: Deleting Output Credentials also removes the association to Output Destinations without warning. This may leave one or more Output Destinations requiring association to different Output Credentials.

Path Parameters

credentials_id string required

Unique identifier of the Output Credentials.

Body Parameters

No parameters.

Returns

Path Parameters

DELETE /v2/output/credentials/{credentials_id}

curl -X DELETE 'https://api.machineq.net/v2/output/credentials/{credentials_id}'

Output Events

Output Events are produced by the MachineQ output system when an Output Alert rule triggers based on the current state of a specified device or gateway.

Endpoints

POSToutputAlertEventWebhook

The Output Events object

Attributes

timestamp string (date-time)

Timestamp of when the connectivity status changed, in RFC 3339 format.

node_id string

Unique node_id of the Gateway whose connectivity status changed.

status enum (string)

Current connectivity status of the Gateway.

online: Gateway is connected and communicating.
offline: Gateway is not communicating.

The Output Events object

{
  "timestamp": "2006-01-02T15:04:05.000Z",
  "node_id": "string",
  "status": "string"
}

Delivers an output alert event Webhook

Delivers an Output Alert Event to each Output Destination associated with the Output Alert when the alert condition is met.

Body Parameters

timestamp string (date-time) required

Timestamp of when the event was processed, in RFC 3339 format.

type enum (string) required

Type of the alert event.

gateway_connectivity: Indicates a change in gateway connectivity status.

data object required

Type-specific event payload.

One of:

Examples

Returns

Webhook Destination

Body

{
  "timestamp": "string",
  "type": "string",
  "data": {
    "timestamp": "string",
    "node_id": "string",
    "status": "string"
  }
}

POST Webhook

curl -X POST '{webhook-url}' \
    -H 'Content-Type: application/json'