Skip to main content

Quickstart

Quickstart​

This guide takes you from an empty account to your first alert. You'll sign in, create an API key, register a machine, send it some readings, and see the alert Haltless raises from your data.

You'll need about 10 minutes, a Haltless account with the administrator role, and curl (or any HTTP client). Every request goes to https://api.haltless.io/api/v1.

note

This is an integration quickstart. You don't install or run any Haltless server yourself; you talk to the hosted API at api.haltless.io.

Step 1: Sign in​

Managing your account through the API uses a Bearer access token. Log in to get one:

curl -X POST https://api.haltless.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "<your-password>" }'
{
  "access_token": "<your-access-token>",
  "token_type": "bearer",
  "mfa_required": false
}

The token lasts 30 minutes. See Authentication for refreshing it, multi-factor authentication, and signing in to one of several organizations.

Step 2: Get an API key​

API keys authenticate the data your machines send in. Create one from the dashboard under Settings → API Keys, or from the API:

curl -X POST https://api.haltless.io/api/v1/settings/api-keys \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "line-3-edge" }'

The response returns the key once. Copy it now, because it is never shown again:

{
  "id": "8c7b1e2a-0f3d-4a9c-9b21-1d6e5f0a7c34",
  "name": "line-3-edge",
  "key": "<your-new-api-key>",
  "scopes": ["ingest", "agent"],
  "kind": "edge_agent",
  "created_at": "2026-08-07T10:00:00Z"
}
warning

Treat the key like a password. Store it in a secret manager, never commit it to source control, and rotate it if it leaks. See Managing API keys.

Step 3: Register a machine​

Readings are accepted only for a System Haltless knows: the connection they come from, such as a PLC or a folder of CSV exports. The quickest way to get one is to register a machine on its own. Haltless creates a System with the same identifier and routes everything it sends to that machine:

curl -X POST https://api.haltless.io/api/v1/machines \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CNC 1", "machine_identifier": "CNC-001", "protocol": "json" }'

You can do the same from the dashboard under Machines → Add machine.

Step 4: Send your first readings​

You have two ways to get data into Haltless.

The Edge Agent runs next to your equipment, reads PLCs, building controllers, MQTT and Sparkplug B brokers, a PI historian, or CSV and JSON files, and streams readings to Haltless for you. Point it at your API key and your System identifier, and data flows automatically. Start with the installation guide.

Option B: Direct ingestion (fastest to try)​

Send readings yourself with a single call. Authenticate with the API key in the X-API-Key header, and name the System with system_identifier:

curl -X POST https://api.haltless.io/api/v1/ingest \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "readings": [
      {
        "system_identifier": "CNC-001",
        "timestamp": "2026-08-07T10:30:00Z",
        "metric_name": "temperature",
        "value": 72.5,
        "unit": "celsius"
      },
      {
        "system_identifier": "CNC-001",
        "timestamp": "2026-08-07T10:30:00Z",
        "metric_name": "vibration",
        "value": 3.2,
        "unit": "mm/s"
      }
    ]
  }'

Haltless reports how many readings landed:

{
  "accepted_count": 2,
  "rejected_count": 0,
  "errors": [],
  "unassigned_count": 0
}

Use the current time for timestamp: a reading may be at most 5 minutes in the future. For the full field list and batching tips, see Direct ingestion.

Step 5: Read your data back​

Reading data uses your access token, not the API key. List your machines:

curl https://api.haltless.io/api/v1/machines \
  -H "Authorization: Bearer <your-access-token>"

That's a complete round trip: you sent data in and read it back out.

Step 6: Receive your first alert​

Haltless raises an alert when a metric stays out of its range for 3 readings in a row. There are two kinds of range:

  • A learned baseline. Haltless learns each metric's normal range from its last 7 days, once it has at least 30 readings. Baselines are recalculated every few hours, so this takes a little while on a new machine.
  • A threshold rule you set. This works straight away. For example, warn above 80 °C and go critical above 90 °C:
curl -X POST https://api.haltless.io/api/v1/alert-rules \
  -H "Authorization: Bearer <your-access-token>" \
  -H "Content-Type: application/json" \
  -d '{ "metric_name": "temperature", "warning_threshold": 80, "critical_threshold": 90 }'

Send three readings above 80 and list your current alerts:

curl https://api.haltless.io/api/v1/alerts \
  -H "Authorization: Bearer <your-access-token>"

You have three ways to receive alerts as they happen:

  • Poll the API: the call above, on a schedule. See Alerts.
  • Stream over WebSocket: get pushed updates the moment they occur. See WebSocket integration.
  • Deliver to your systems: have Haltless POST each alert to an endpoint you control. See Webhook setup.
tip

Batch readings: one POST /api/v1/ingest call can carry up to 1,000 of them, and ingest requests are limited to 600 per minute from each network address. See Rate limiting.

What's next​