API Overview

The Haltless REST API is a JSON-over-HTTPS interface for connecting Systems, ingesting sensor telemetry, and managing machines, alerts, maintenance, work orders, downtime, OEE, and the rest of your account. This reference documents the public endpoints, their request parameters, and their response shapes.

Base URL

All requests are made to:

https://api.haltless.io

Every endpoint in this reference is versioned under the /api/v1 prefix. For example, the machines collection is:

https://api.haltless.io/api/v1/machines

Throughout the rest of this reference, paths are written in their short form (for example /api/v1/machines). The one exception is the unauthenticated health check, GET /health, which sits outside the prefix and returns 200 when the service is healthy and 503 when it is not.

Authentication

Most endpoints require a bearer JWT, which you get by signing in:

Authorization: Bearer <jwt>

API keys use a different header:

X-API-Key: <api-key>

There are two kinds of API key:

• Edge-agent keys carry scopes. With the default scopes (ingest, agent) they send readings to POST /api/v1/ingest and call the edge-agent heartbeat. The read:machines and read:sensors scopes add read-only access to GET /api/v1/machines, GET /api/v1/machines/{machine_id}, and that machine's readings, readings/latest, and summary.
• Service-account keys act as a member of your company with a role, and can call whatever a person in that role can, except user, role, API-key, and sign-in management.

See Authentication for how to obtain and refresh tokens, and the API Keys guide for issuing keys.

Request format

• Content-Type: send application/json for all request bodies, except file uploads, which use multipart/form-data.
• Character encoding: UTF-8.
• Timestamps: ISO 8601 in UTC (for example 2026-08-07T10:30:00Z).
• Identifiers: resource IDs are UUIDs.
• Size: request bodies are limited to 10 MB.

Response format

Responses are JSON. Successful requests return one of:

Code	Meaning
200	Success
201	Resource created
204	Success with no body (for example a delete)
207	Multi-status (batch ingestion)

See Errors for the full list of error codes and the error body shape.

Pagination

Collection endpoints that page use the following query parameters:

Parameter	Type	Default	Max
page	integer	1
page_size	integer	20	100

Paginated responses wrap the results in an items array alongside a pagination object:

{
  "items": [],
  "pagination": {
    "total": 150,
    "page": 1,
    "page_size": 20
  }
}

Rate limiting

Limits are the same for every company and depend on the kind of request. Signed-in requests share one budget per company; ingestion is counted per network address. See Rate Limiting for the exact budgets and the response headers.

Endpoint catalog

Fundamentals

Resource	Description
Authentication	Sign in, refresh tokens, multi-factor authentication, and single sign-on
Rate Limiting	Request budgets and how to handle 429
Errors	Status codes and error bodies

Core resources

Resource	Description
Systems	The connections the edge agent reads, and assigning their tags to machines
Machines	Register and manage machines, groups, tag mappings, and units
Sensor Data	Ingest telemetry, query time-series readings, and manage polled OPC-UA and Modbus sources
Alerts	List, acknowledge, snooze, and comment on alerts
Alert Rules	Configure threshold, composite, and escalation rules

Operations

Resource	Description
Maintenance	Schedule and track maintenance events
Work Orders	Manage work orders, instructions, comments, and attachments
Downtime	Record downtime, reason codes, and reliability KPIs
OEE	Submit and summarize Overall Equipment Effectiveness
Shifts	Shift definitions, shift logs, handover reports, and comparisons
Compliance	Digital sign-offs and completion certificates for work orders
Inventory	Spare parts, stock transactions, and parts used on work orders

Intelligence

Resource	Description
Fleet	Fleet status, site KPIs, and the edge-agent heartbeat
Predictions	Machine health scores, remaining-life estimates, and anomaly summaries
Reports	PDF and CSV reports and saved report templates

Integration

Resource	Description
ERP	Connections to SAP, Dynamics 365, and Oracle, syncs, and sync logs
Notifications	Notification channels (webhook, email, Slack, and more) and web push
WebSocket	Live readings and alerts over one connection

Administration

Resource	Description
Settings	Profile, API keys, notification and unit preferences, team members, and roles
Audit	Your company's audit log
Invoices	The invoices Haltless has issued to your company