SapienStream

Machines API

Industrial equipment registry and management. Register machines, configure protocol adapters, and monitor operational status across your industrial automation infrastructure.

Overview

Protocol Support

  • • OPC-UA: Industrial communication standard
  • • Modbus TCP/RTU: Legacy protocol support
  • • Siemens S7: Native S7 connectivity
  • • EtherNet/IP: Allen-Bradley integration
  • • Simulation: Testing and development

Machine Management

  • • Machine registration and configuration
  • • Real-time status monitoring
  • • Adapter-specific settings
  • • Location and metadata tracking
  • • Operational statistics

Machine Data Model

Machine Properties
Core fields and configuration options for industrial machines
{
  "id": "machine_12345",
  "name": "Production Line 1",
  "vendor": "Siemens",
  "model": "S7-1500",
  "location": "Factory Floor A, Section 2",
  "adapter": "s7",
  "adapter_config": {
    "host": "192.168.1.100",
    "port": 102,
    "rack": 0,
    "slot": 1,
    "connection_timeout": 30
  },
  "description": "Main production line controller",
  "machine_metadata": {
    "department": "Manufacturing",
    "cost_center": "CC-001",
    "installation_date": "2024-01-15"
  },
  "is_active": true,
  "last_seen": "2024-08-26T10:30:00Z",
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-08-26T10:30:00Z"
}

API Endpoints

GET/machinesAuth Required
List Machines
Retrieve a list of registered machines with optional filtering and pagination.

Parameters

active_onlyboolean

Show only active machines (default: false)

vendorstring

Filter by vendor name

adapterstring

Filter by adapter type (sim, opcua, modbus, s7, ethernet_ip)

locationstring

Filter by location (partial match)

searchstring

Search in name, vendor, model fields

limitinteger

Maximum number of results (max: 100, default: 50)

offsetinteger

Number of results to skip (default: 0)

Response

Responsejson
[
  {
    "id": "machine_001",
    "name": "Production Line 1",
    "vendor": "Siemens",
    "model": "S7-1500",
    "location": "Factory Floor A",
    "adapter": "s7",
    "is_active": true,
    "last_seen": "2024-08-26T10:30:00Z",
    "tag_count": 45,
    "semantic_tag_count": 12,
    "document_count": 3
  }
]

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/machines" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
POST/machinesAuth Required
Create Machine
Register a new industrial machine with protocol adapter configuration.

Request Body

Requestjson
{
  "name": "Production Line 2",
  "vendor": "Allen-Bradley",
  "model": "CompactLogix L32E",
  "location": "Factory Floor B, Section 1",
  "adapter": "ethernet_ip",
  "adapter_config": {
    "host": "192.168.1.101",
    "port": 44818,
    "path": "1,0"
  },
  "description": "Secondary production line controller",
  "machine_metadata": {
    "department": "Manufacturing",
    "cost_center": "CC-002"
  }
}

Response

Responsejson
{
  "id": "machine_002",
  "name": "Production Line 2",
  "vendor": "Allen-Bradley",
  "model": "CompactLogix L32E",
  "location": "Factory Floor B, Section 1",
  "adapter": "ethernet_ip",
  "adapter_config": {
    "host": "192.168.1.101",
    "port": 44818,
    "path": "1,0"
  },
  "description": "Secondary production line controller",
  "machine_metadata": {
    "department": "Manufacturing",
    "cost_center": "CC-002"
  },
  "is_active": true,
  "last_seen": null,
  "created_at": "2024-08-26T11:00:00Z",
  "updated_at": "2024-08-26T11:00:00Z",
  "created_by": "user_123",
  "updated_by": "user_123"
}

Try it out

cURLbash
curl -X POST "https://sapienstream.com/api/machines" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/machines/{id}Auth Required
Get Machine Details
Retrieve detailed information about a specific machine including related counts.

Parameters

idstringRequired

Machine unique identifier

Response

Responsejson
{
  "id": "machine_001",
  "name": "Production Line 1",
  "vendor": "Siemens",
  "model": "S7-1500",
  "location": "Factory Floor A, Section 2",
  "adapter": "s7",
  "adapter_config": {
    "host": "192.168.1.100",
    "port": 102,
    "rack": 0,
    "slot": 1
  },
  "description": "Main production line controller",
  "machine_metadata": {
    "department": "Manufacturing",
    "cost_center": "CC-001"
  },
  "is_active": true,
  "last_seen": "2024-08-26T10:30:00Z",
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-08-26T10:30:00Z",
  "created_by": "admin",
  "updated_by": "user_123"
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/machines/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
PUT/machines/{id}Auth Required
Update Machine
Update machine configuration, adapter settings, or metadata.

Parameters

idstringRequired

Machine unique identifier

Request Body

Requestjson
{
  "name": "Production Line 1 - Updated",
  "location": "Factory Floor A, Section 3",
  "adapter_config": {
    "host": "192.168.1.105",
    "port": 102,
    "rack": 0,
    "slot": 1,
    "connection_timeout": 45
  },
  "description": "Main production line controller - relocated",
  "is_active": true
}

Response

Responsejson
{
  "id": "machine_001",
  "name": "Production Line 1 - Updated",
  "vendor": "Siemens",
  "model": "S7-1500",
  "location": "Factory Floor A, Section 3",
  "adapter": "s7",
  "adapter_config": {
    "host": "192.168.1.105",
    "port": 102,
    "rack": 0,
    "slot": 1,
    "connection_timeout": 45
  },
  "description": "Main production line controller - relocated",
  "machine_metadata": {
    "department": "Manufacturing",
    "cost_center": "CC-001"
  },
  "is_active": true,
  "last_seen": "2024-08-26T10:30:00Z",
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-08-26T11:15:00Z",
  "created_by": "admin",
  "updated_by": "user_456"
}

Try it out

cURLbash
curl -X PUT "https://sapienstream.com/api/machines/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
DELETE/machines/{id}Auth Required
Delete Machine
Delete a machine and all associated tags, semantic tags, and documents.

Parameters

idstringRequired

Machine unique identifier

Response

Responsejson
{
  "message": "Machine deleted successfully",
  "deleted_id": "machine_001",
  "deleted_at": "2024-08-26T11:30:00Z"
}

Try it out

cURLbash
curl -X DELETE "https://sapienstream.com/api/machines/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
GET/machines/statsAuth Required
Machine Statistics
Get aggregated statistics about all machines in the system.

Response

Responsejson
{
  "total_machines": 15,
  "active_machines": 12,
  "inactive_machines": 3,
  "by_adapter": {
    "s7": 6,
    "opcua": 4,
    "modbus": 3,
    "ethernet_ip": 2
  },
  "by_vendor": {
    "Siemens": 8,
    "Allen-Bradley": 4,
    "Schneider Electric": 3
  },
  "recently_offline": 2
}

Try it out

cURLbash
curl -X GET "https://sapienstream.com/api/machines/stats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Adapter Configuration Examples

Siemens S7
Native S7 protocol configuration
{
  "adapter": "s7",
  "adapter_config": {
    "host": "192.168.1.100",
    "port": 102,
    "rack": 0,
    "slot": 1,
    "connection_timeout": 30,
    "read_timeout": 10
  }
}
OPC-UA
Industrial standard OPC-UA configuration
{
  "adapter": "opcua",
  "adapter_config": {
    "endpoint": "opc.tcp://192.168.1.100:4840",
    "security_policy": "None",
    "security_mode": "None",
    "username": "opcuser",
    "password": "password123",
    "session_timeout": 60000
  }
}
Modbus TCP
Legacy Modbus protocol configuration
{
  "adapter": "modbus",
  "adapter_config": {
    "host": "192.168.1.100",
    "port": 502,
    "unit_id": 1,
    "timeout": 10,
    "byte_order": "big_endian",
    "word_order": "big_endian"
  }
}
EtherNet/IP
Allen-Bradley protocol configuration
{
  "adapter": "ethernet_ip",
  "adapter_config": {
    "host": "192.168.1.100",
    "port": 44818,
    "path": "1,0",
    "timeout": 5000,
    "connection_size": 508,
    "large_packet_usage": true
  }
}

Error Responses

Common Error Codes

400 Bad Request

{
  "detail": "Invalid adapter configuration: missing required field 'host'"
}

404 Not Found

{
  "detail": "Machine with id 'machine_999' not found"
}

409 Conflict

{
  "detail": "Machine with name 'Production Line 1' already exists in this location"
}