SapienStream

API Reference

Complete reference documentation for the SapienStream API. Build powerful industrial applications with our comprehensive REST API.

Getting Started

Base URL
https://sapienstream.com/api
Authentication Required

All API endpoints require authentication via JWT Bearer token.

Authorization: Bearer YOUR_JWT_TOKEN

Core APIs

Machines API
Industrial equipment registry and management
GET

/machines - List all machines

POST

/machines - Create new machine

PUT

/machines/{id} - Update machine

Supported Protocols:

OPC-UAModbusS7EtherNet/IP
View Documentation →
Tags API
Real-time machine data and tag operations
GET

/tags - List machine tags

POST

/tags - Create new tag

PUT

/tags/{machine_id}/{name}/write - Write value

Data Types:

BOOLINTREALSTRING
View Documentation →
Semantic Tags
High-level abstractions and operational metrics
GET

/semantic-tags - List semantic tags

POST

/semantic-tags - Create semantic tag

PUT

/semantic-tags/{id} - Update tag

Semantic Types:

AnalogDigitalStateCounter
View Documentation →
Documents API
Compliance and regulatory documentation
GET

/documents - List documents

POST

/documents - Upload document

DELETE

/documents/{id} - Delete document

Document Types:

ManualCertificateSDS
View Documentation →
Components API
Industrial component marketplace and registry
GET

/components/search - Search components

GET

/components/{id} - Component details

GET

/components/categories - List categories

Categories:

SensorsActuatorsMotorsValves
View Documentation →
Authentication
User management and security
POST

/auth/login - User login

POST

/auth/register - User registration

GET

/auth/me - Current user info

Features:

JWTRBACMFAAPI Keys
View Documentation →

Complete Workflow Example

Industrial Data Collection Setup
End-to-end example showing how to register a machine, create tags, and collect data

1. Authenticate and Get Token

curl -X POST "https://sapienstream.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

2. Register a New Machine

curl -X POST "https://sapienstream.com/api/machines" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Line 1",
    "vendor": "Siemens",
    "model": "S7-1500",
    "location": "Factory Floor A",
    "adapter": "s7",
    "adapter_config": {
      "host": "192.168.1.100",
      "port": 102,
      "rack": 0,
      "slot": 1
    },
    "description": "Main production line controller"
  }'

3. Create Tags for Data Points

curl -X POST "https://sapienstream.com/api/tags" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_id": "MACHINE_ID_FROM_STEP_2",
    "name": "Temperature_Sensor_01",
    "datatype": "REAL",
    "description": "Main production temperature",
    "unit": "°C",
    "min_value": 0,
    "max_value": 100,
    "is_writable": false
  }'

4. Create Semantic Tag Abstraction

curl -X POST "https://sapienstream.com/api/semantic-tags" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_id": "MACHINE_ID_FROM_STEP_2",
    "canonical_name": "Production_Temperature",
    "source_tags": ["Temperature_Sensor_01"],
    "semantic_type": "Analog",
    "unit": "°C",
    "criticality": "high",
    "limits": {
      "min": 0,
      "max": 100,
      "warning_high": 85,
      "alarm_high": 95
    },
    "description": "Critical production temperature monitoring"
  }'

5. Read Tag Values

curl -X GET "https://sapienstream.com/api/tags?machine_id=MACHINE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

API Guidelines

Rate Limits
  • • Standard: 1000 requests/hour
  • • Burst: 100 requests/minute
  • • Tag Writes: 500 writes/hour
  • • File Uploads: 50 uploads/hour
  • • Rate limit headers included in responses
Best Practices
  • • Use appropriate HTTP methods and status codes
  • • Implement exponential backoff for retries
  • • Cache authentication tokens appropriately
  • • Use pagination for large result sets
  • • Monitor API usage and response times