Skip to main content

Quickstart

Quickstart​

This guide takes you from an empty account to your first anomaly alert. You'll create an API key, send a machine reading, make your first authenticated API call, and see the alert Haltless raises from your data.

You'll need about 10 minutes, a Haltless account, 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 — 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 with an account-admin access token (see Authentication for how to log in and get a token):

curl -X POST https://api.haltless.io/api/v1/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>",
  "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 2 — Send your first machine reading​

You have two ways to get data into Haltless.

Option A — The Edge Agent (recommended for production)​

The Edge Agent runs next to your equipment, reads from OPC-UA, Modbus, CSV, or JSON sources, and streams readings to Haltless for you. Point it at your API key and your machines, 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:

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

Haltless accepts each reading independently and reports how many landed:

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

The machine_identifier is your own label for the machine. Send a steady stream of readings for it and Haltless learns its normal operating range. For the full field list and batching tips, see Direct ingestion.

Step 3 — Make your first authenticated API call​

Reading data back uses a Bearer access token rather than an API key. 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
}

Now list your machines, sending the token in the Authorization header:

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. See Authentication for token lifetimes, refresh, and MFA.

Step 4 — Receive your first alert​

As readings arrive, Haltless runs anomaly detection on them. When a machine drifts outside its normal range, an alert is raised. 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

Rate limits are uniform across every account: 120 writes/min, 600 reads/min, and 240 ingest requests/min. Batch multiple readings into one POST /api/v1/ingest call to stay well within them. See Rate limiting.

What's next​