API Reference
Complete reference documentation for the SapienStream API. Build powerful industrial applications with our comprehensive REST API.
Getting Started
https://sapienstream.com/apiAll API endpoints require authentication via JWT Bearer token.
Authorization: Bearer YOUR_JWT_TOKENCore APIs
/v1/machines - List all machines
/v1/machines - Create new machine
/v1/machines/{id} - Update machine
Supported Protocols:
/v1/tags - List machine tags
/v1/tags - Create new tag
/v1/tags/{machine_id}/{name}/write - Write value
Data Types:
/v1/semantic-tags - List semantic tags
/v1/semantic-tags - Create semantic tag
/v1/semantic-tags/{id} - Update tag
Semantic Types:
/v1/documents - List documents
/v1/documents - Upload document
/v1/documents/{id} - Delete document
Document Types:
/v1/components/search - Search components
/v1/components/{id} - Component details
/v1/components/categories/stats - Category statistics
Categories:
/v1/auth/login - User login
/v1/auth/register - User registration
/v1/auth/me - Current user info
Features:
/v1/nelo/chat - Send message to Nelo
/v1/nelo/sessions - Chat sessions
/v1/nelo/tools - Execute AI tools
Features:
/v1/api-keys - List API keys
/v1/api-keys - Create new key
/v1/api-keys/usage - Usage analytics
Features:
/v1/billing/llm/overview - Token usage
/v1/payments/subscription - Status
/v1/payments/checkout-session - Pay
Features:
/v1/storage/buckets/initialize - Init buckets
/v1/storage/upload - Upload file
/v1/storage/usage - Usage analytics
Features:
/v1/semantic-graph/knowledge-graph - Full graph
/v1/semantic-graph/overview - Overview
/v1/semantic-graph/relationships - Relations
Features:
/v1/pdf/extract-component - Extract data
/v1/pdf/processing-status/{id} - Status
/v1/pdf/detect-catalog - Detect type
Features:
/v1/dashboard/overview - All stats
/v1/dashboard/activity - Activity feed
/v1/dashboard/machine-stats - Machine stats
Features:
/v1/facilities - List facilities
/v1/units - List units
/v1/machines/{id}/location - Assign
Features:
/v1/global-files - List files
/v1/global-files - Upload file
/v1/global-files/{id}/download - Download
Features:
/v1/realtime-data/ingest - Ingest sensor data
/v1/realtime-data/machines/{id}/data
/v1/realtime-data/machines/{id}/latest
Features:
Complete Workflow Example
1. Authenticate and Get Token
curl -X POST "https://sapienstream.com/api/v1/auth/login" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=your_username&password=your_password"2. Register a New Machine
curl -X POST "https://sapienstream.com/api/v1/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
},
"raw_tags": [],
"description": "Main production line controller"
}'3. Create Tags for Data Points
curl -X POST "https://sapienstream.com/api/v1/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/v1/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/v1/tags?machine_id=MACHINE_ID" \
-H "Authorization: Bearer YOUR_TOKEN"API Guidelines
- • Standard: 1000 requests/hour
- • Burst: 100 requests/minute
- • Tag Writes: 500 writes/hour
- • File Uploads: 50 uploads/hour
- • Rate limit headers included in responses
- • 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