Quick Start

Get up and running with the Haltless API in 5 minutes. By the end of this guide, you'll have created an API key, pushed a sensor reading, and queried your data.

Prerequisites

• A Haltless account (sign up at app.haltless.io)
• curl or any HTTP client
• Your machine identifier (e.g., CNC-001)

Step 1: Create an API key

Log in to the Haltless dashboard and navigate to Settings > API Keys. Click Create API Key, give it a name, and copy the key immediately , it's only shown once.

Alternatively, create one via the API (requires admin JWT):

curl -X POST https://api.haltless.io/api/v1/settings/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "edge-agent-prod"}'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "edge-agent-prod",
  "key_prefix": "hk_abc12",
  "plaintext_key": "hk_abc12345...full_key_here",
  "created_at": "2026-04-04T10:00:00Z"
}

caution

Save the plaintext_key value immediately. It cannot be retrieved after creation.

Step 2: Register a machine

Before pushing data, ensure a machine exists in your tenant. Create one through the dashboard or API:

curl -X POST https://api.haltless.io/api/v1/machines \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CNC Mill #1",
    "machine_identifier": "CNC-001",
    "protocol": "json",
    "location": "Building A, Line 3"
  }'

Step 3: Push sensor data

Use the batch ingestion endpoint with your API key:

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-04-04T10:30:00Z",
        "metric_name": "temperature",
        "value": 72.5,
        "unit": "celsius"
      },
      {
        "machine_identifier": "CNC-001",
        "timestamp": "2026-04-04T10:30:00Z",
        "metric_name": "vibration",
        "value": 3.2,
        "unit": "mm/s"
      }
    ]
  }'

Response (HTTP 207 Multi-Status):

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

Step 4: Query your data

Retrieve the latest readings for your machine:

curl https://api.haltless.io/api/v1/machines/MACHINE_ID/readings/latest \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Query time-series data with aggregation:

curl "https://api.haltless.io/api/v1/machines/MACHINE_ID/readings?metric=temperature&interval=5m&start=2026-04-04T00:00:00Z" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Step 5: Check fleet status

Get a bird's-eye view of all your machines:

curl https://api.haltless.io/api/v1/fleet/status \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

{
  "total_machines": 1,
  "machines": [
    {
      "id": "...",
      "name": "CNC Mill #1",
      "status": "healthy",
      "alert_count": 0,
      "last_reading_at": "2026-04-04T10:30:00Z"
    }
  ]
}

What's next?

• Set up the edge agent for continuous data collection
• Configure alert rules for threshold monitoring
• Connect a WebSocket for real-time updates
• Explore the full API to see all available endpoints