API Documentation

Authentication

All API requests must include a valid Bearer token in the Authorization header. Tokens are issued per-organization and can be generated from the dashboard settings page.

Authorization: Bearer mqk_live_a1b2c3d4e5f6...

Note: API tokens carry full access to your organization data. Treat them as credentials and never expose them in client-side code or version control.

Base URL

All endpoints are relative to the following base URL:

https://metriqo.net/api/v2

Error Handling

The API returns standard HTTP status codes. Error responses include a JSON body with a machine-readable error code and a human-readable message.

{
  "error": "unauthorized",
  "message": "Invalid or expired API token."
}

Status	Meaning
200	Request succeeded
201	Resource created
400	Bad request (malformed payload)
401	Unauthorized (missing or invalid token)
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Endpoints

POST /api/v2/telemetry

Ingest telemetry data from one or more devices. Each payload contains a device identifier, a timestamp, and a map of metric key-value pairs. Metriqo accepts batched submissions of up to 100 data points per request.

Request Headers

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Request Body

Field	Type	Description
`device_id`	string	Unique device identifier required
`timestamp`	string (ISO 8601)	Measurement timestamp. Defaults to server time if omitted.
`metrics`	object	Key-value pairs of metric names and numeric values required

Example Request

# Send device telemetry
curl -X POST https://metriqo.net/api/v2/telemetry \
  -H "Authorization: Bearer mqk_live_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "sensor-gw-0417",
    "timestamp": "2024-11-15T08:32:00Z",
    "metrics": {
      "cpu_temp": 62.4,
      "mem_used_mb": 214,
      "uptime_sec": 874200,
      "error_count": 0
    }
  }'

Example Response

// 201 Created
{
  "status": "accepted",
  "points_written": 4,
  "device_id": "sensor-gw-0417"
}

Error Response (401)

// 401 Unauthorized
{
  "error": "unauthorized",
  "message": "Invalid or expired API token."
}

GET /api/v2/devices

Retrieve a paginated list of devices registered to your organization, including their last seen timestamps and current status.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page, max 100 (default: 25)
`status`	string	Filter by status: `online`, `offline`, `inactive`

Example Request

# List online devices
curl https://metriqo.net/api/v2/devices?page=1&per_page=10&status=online \
  -H "Authorization: Bearer mqk_live_a1b2c3d4e5f6"

Example Response

// 200 OK
{
  "data": [
    {
      "device_id": "sensor-gw-0417",
      "label": "Gateway Floor 4",
      "status": "online",
      "last_seen": "2024-11-15T08:32:00Z",
      "created_at": "2024-03-10T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 47
  }
}

GET /api/v2/metrics

Query historical metric data for a specific device over a time range. Returns time-series data points sorted by timestamp in ascending order.

Query Parameters

Parameter	Type	Description
`device_id`	string	Target device identifier required
`metric`	string	Metric name (e.g. `cpu_temp`) required
`from`	string (ISO 8601)	Start of time range required
`to`	string (ISO 8601)	End of time range required
`interval`	string	Aggregation interval: `1m`, `5m`, `1h`, `1d`

Example Request

# Query hourly CPU temperature for a device
curl "https://metriqo.net/api/v2/metrics?\
device_id=sensor-gw-0417&\
metric=cpu_temp&\
from=2024-11-14T00:00:00Z&\
to=2024-11-15T00:00:00Z&\
interval=1h" \
  -H "Authorization: Bearer mqk_live_a1b2c3d4e5f6"

Example Response

// 200 OK
{
  "device_id": "sensor-gw-0417",
  "metric": "cpu_temp",
  "interval": "1h",
  "data": [
    { "t": "2024-11-14T00:00:00Z", "avg": 58.2, "min": 54.1, "max": 63.8 },
    { "t": "2024-11-14T01:00:00Z", "avg": 57.6, "min": 53.9, "max": 62.4 },
    { "t": "2024-11-14T02:00:00Z", "avg": 56.1, "min": 52.0, "max": 60.3 }
  ]
}

POST /api/v2/alerts

Create a threshold-based alert rule for a device or group of devices. When the specified metric crosses the threshold, Metriqo sends a notification to the configured destination.

Request Body

Field	Type	Description
`name`	string	Human-readable alert name required
`device_id`	string	Target device (or `"*"` for all devices) required
`metric`	string	Metric to monitor required
`condition`	string	Comparison: `gt`, `lt`, `gte`, `lte` required
`threshold`	number	Trigger value required
`notify`	object	Notification target: `{"type": "webhook", "url": "..."}` required

Example Request

# Create a temperature alert
curl -X POST https://metriqo.net/api/v2/alerts \
  -H "Authorization: Bearer mqk_live_a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High CPU Temperature",
    "device_id": "sensor-gw-0417",
    "metric": "cpu_temp",
    "condition": "gt",
    "threshold": 80,
    "notify": {
      "type": "webhook",
      "url": "https://ops.example.com/hooks/thermal"
    }
  }'

Example Response

// 201 Created
{
  "id": "alert_xK7mQ2",
  "name": "High CPU Temperature",
  "status": "active",
  "created_at": "2024-11-15T09:10:00Z"
}

Rate Limits

API requests are rate-limited per organization. The current limits are:

Endpoint	Limit
`POST /telemetry`	1,000 requests/min
`GET /devices`	300 requests/min
`GET /metrics`	300 requests/min
`POST /alerts`	60 requests/min

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Metriqo API Documentation

Authentication

Base URL

Error Handling

Endpoints

Request Headers

Request Body

Example Request

Example Response

Error Response (401)

Query Parameters

Example Request

Example Response

Query Parameters

Example Request

Example Response

Request Body

Example Request

Example Response

Rate Limits