Machines

Manage your machine fleet , register, update, query, and organize machines into groups.

Create a machine

POST /machines

Auth: Bearer JWT (admin, operator)

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

Request body:

Field	Type	Required	Description
name	string	Yes	Human-readable name
machine_identifier	string	Yes	Unique identifier (used in ingestion)
protocol	string	Yes	opc_ua, modbus_tcp, csv, json
location	string	No	Physical location

Response 201:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CNC Mill #1",
  "machine_identifier": "CNC-001",
  "protocol": "json",
  "location": "Building A, Line 3",
  "status": "offline",
  "tenant_id": "...",
  "is_active": true,
  "created_at": "2026-04-04T10:00:00Z",
  "updated_at": "2026-04-04T10:00:00Z"
}

List machines

GET /machines

Auth: Bearer JWT (any role)

Parameter	Type	Default	Description
page	int	1	Page number
page_size	int	20	Items per page (max 100)
group_id	uuid	-	Filter by machine group
search	string	-	Search by name/identifier (max 200 chars)
status	string	-	Filter by status: healthy, warning, critical, offline
sort_by	string	name	Sort field
sort_dir	string	asc	asc or desc

curl "https://api.haltless.io/api/v1/machines?status=critical&page_size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "items": [
    {
      "id": "...",
      "name": "CNC Mill #1",
      "machine_identifier": "CNC-001",
      "status": "critical",
      "protocol": "json",
      "location": "Building A",
      "created_at": "2026-04-04T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "total_pages": 1
}

Get a machine

GET /machines/{machine_id}

Auth: Bearer JWT (any role)

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

Update a machine

PATCH /machines/{machine_id}

Auth: Bearer JWT (admin, operator)

curl -X PATCH https://api.haltless.io/api/v1/machines/MACHINE_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"location": "Building B, Line 1"}'

All fields are optional , only include fields you want to change.

Delete a machine

DELETE /machines/{machine_id}

Auth: Bearer JWT (admin, operator)

Performs a soft-delete (machine is deactivated, not permanently removed).

curl -X DELETE https://api.haltless.io/api/v1/machines/MACHINE_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

Import machines (CSV/XLSX)

POST /machines/import

Auth: Bearer JWT (admin, operator)

Bulk import up to 500 machines from a CSV or XLSX file.

curl -X POST https://api.haltless.io/api/v1/machines/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@machines.csv"

Required columns: name, machine_identifier, protocol

Optional columns: location

Response:

{
  "created": 45,
  "skipped": 3,
  "errors": [
    {"row": 12, "error": "Duplicate machine_identifier: CNC-003"}
  ]
}

Machine groups

Organize machines into hierarchical groups (sites, lines, departments).

Create a group

POST /machine-groups

Auth: Bearer JWT (admin, operator)

{
  "name": "Building A",
  "group_type": "site",
  "parent_id": null,
  "description": "Main production facility"
}

Group types: site, line, department, custom

List groups

GET /machine-groups

Get group tree

GET /machine-groups/tree

Returns the full hierarchy as a nested tree structure.

Update group members

PUT /machine-groups/{group_id}/members

{
  "machine_ids": ["uuid1", "uuid2", "uuid3"]
}

Machine statuses

Status	Description
healthy	All metrics within normal baselines
warning	One or more metrics above warning threshold
critical	One or more metrics above critical threshold
offline	No readings received recently

Statuses are computed automatically based on sensor data and alert rules.