/ Documentation

Tags API

Real-time machine data and tag operations. Manage raw signals and variables from industrial automation equipment with type safety and quality indicators.

Overview

Data Types

• BOOL: Boolean values (True/False)
• INT: Integer numbers
• REAL: Floating point numbers
• STRING: Text strings

Features

• Real-time value monitoring
• Data quality indicators
• Write operation tracking
• Value validation and limits
• Audit trail logging

Tag Data Model

Tag Properties

Core fields and metadata for industrial automation tags

{
  "machine_id": "machine_001",
  "name": "Temperature_Sensor_01",
  "datatype": "REAL",
  "value": 85.7,
  "timestamp": "2024-08-26T10:30:15Z",
  "description": "Main reactor temperature sensor",
  "unit": "°C",
  "min_value": 0,
  "max_value": 150,
  "quality": "GOOD",
  "is_writable": false,
  "is_active": true,
  "last_write_by": null,
  "last_write_at": null,
  "write_count": 0,
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-08-26T10:30:15Z"
}

Data Quality

GOOD

Tag value is reliable and within expected parameters. Normal operation.

UNCERTAIN

Tag value may be unreliable due to communication issues or sensor drift.

BAD

Tag value is invalid due to communication failure or sensor malfunction.

API Endpoints

GET/tagsAuth Required

List Tags

Retrieve tags with filtering, pagination, and optional value inclusion.

Parameters

machine_idstring

Filter tags by machine ID

datatypestring

Filter by data type (BOOL, INT, REAL, STRING)

active_onlyboolean

Show only active tags (default: true)

writable_onlyboolean

Show only writable tags (default: false)

include_valuesboolean

Include current tag values (default: true)

qualitystring

Filter by quality (GOOD, UNCERTAIN, BAD)

searchstring

Search in tag name and description

limitinteger

Maximum results (max: 1000, default: 100)

offsetinteger

Results to skip (default: 0)

Response

Responsejson

[
  {
    "machine_id": "machine_001",
    "name": "Temperature_Sensor_01",
    "datatype": "REAL",
    "value": 85.7,
    "timestamp": "2024-08-26T10:30:15Z",
    "description": "Main reactor temperature",
    "unit": "°C",
    "quality": "GOOD",
    "is_writable": false,
    "is_active": true
  },
  {
    "machine_id": "machine_001", 
    "name": "Motor_Running",
    "datatype": "BOOL",
    "value": true,
    "timestamp": "2024-08-26T10:30:10Z",
    "description": "Motor running status",
    "quality": "GOOD",
    "is_writable": true,
    "is_active": true
  }
]

Try it out

cURLbash

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

POST/tagsAuth Required

Create Tag

Create a new tag definition for a machine.

Request Body

Requestjson

{
  "machine_id": "machine_001",
  "name": "Pressure_Sensor_02", 
  "datatype": "REAL",
  "description": "Secondary pressure measurement",
  "unit": "bar",
  "min_value": 0,
  "max_value": 10,
  "is_writable": false
}

Response

Responsejson

{
  "machine_id": "machine_001",
  "name": "Pressure_Sensor_02",
  "datatype": "REAL",
  "value": null,
  "timestamp": null,
  "description": "Secondary pressure measurement",
  "unit": "bar",
  "min_value": 0,
  "max_value": 10,
  "quality": null,
  "is_writable": false,
  "is_active": true,
  "last_write_by": null,
  "last_write_at": null,
  "write_count": 0,
  "created_at": "2024-08-26T11:00:00Z",
  "updated_at": "2024-08-26T11:00:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/tags/{machine_id}/{name}Auth Required

Get Tag Details

Retrieve detailed information about a specific tag including current value.

Parameters

machine_idstringRequired

Machine unique identifier

namestringRequired

Tag name

Response

Responsejson

{
  "machine_id": "machine_001",
  "name": "Temperature_Sensor_01",
  "datatype": "REAL",
  "value": 85.7,
  "timestamp": "2024-08-26T10:30:15Z",
  "description": "Main reactor temperature sensor",
  "unit": "°C",
  "min_value": 0,
  "max_value": 150,
  "quality": "GOOD",
  "is_writable": false,
  "is_active": true,
  "last_write_by": null,
  "last_write_at": null,
  "write_count": 0,
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-08-26T10:30:15Z"
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/tags/{machine_id}/{name}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

PUT/tags/{machine_id}/{name}/writeAuth Required

Write Tag Value

Write a new value to a writable tag with optional quality and timestamp.

Parameters

machine_idstringRequired

Machine unique identifier

namestringRequired

Tag name

Request Body

Requestjson

{
  "value": 92.3,
  "quality": "GOOD",
  "timestamp": "2024-08-26T11:15:00Z"
}

Response

Responsejson

{
  "success": true,
  "message": "Tag value written successfully",
  "tag": {
    "machine_id": "machine_001",
    "name": "Setpoint_Temperature",
    "datatype": "REAL", 
    "value": 92.3,
    "timestamp": "2024-08-26T11:15:00Z",
    "quality": "GOOD",
    "last_write_by": "user_123",
    "last_write_at": "2024-08-26T11:15:00Z",
    "write_count": 15
  }
}

Try it out

cURLbash

curl -X PUT "https://sapienstream.com/api/tags/{machine_id}/{name}/write" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

PUT/tags/{machine_id}/{name}Auth Required

Update Tag Configuration

Update tag metadata, limits, or settings (not the value).

Parameters

machine_idstringRequired

Machine unique identifier

namestringRequired

Tag name

Request Body

Requestjson

{
  "description": "Updated temperature sensor description",
  "unit": "°F",
  "min_value": 32,
  "max_value": 302,
  "is_writable": true,
  "is_active": true
}

Response

Responsejson

{
  "machine_id": "machine_001",
  "name": "Temperature_Sensor_01",
  "datatype": "REAL",
  "value": 185.26,
  "timestamp": "2024-08-26T10:30:15Z",
  "description": "Updated temperature sensor description",
  "unit": "°F",
  "min_value": 32,
  "max_value": 302,
  "quality": "GOOD",
  "is_writable": true,
  "is_active": true,
  "last_write_by": null,
  "last_write_at": null,
  "write_count": 0,
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-08-26T11:20:00Z"
}

Try it out

cURLbash

curl -X PUT "https://sapienstream.com/api/tags/{machine_id}/{name}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

DELETE/tags/{machine_id}/{name}Auth Required

Delete Tag

Delete a tag definition and all associated data.

Parameters

machine_idstringRequired

Machine unique identifier

namestringRequired

Tag name

Response

Responsejson

{
  "message": "Tag deleted successfully",
  "deleted_tag": {
    "machine_id": "machine_001",
    "name": "Obsolete_Sensor"
  },
  "deleted_at": "2024-08-26T11:30:00Z"
}

Try it out

cURLbash

curl -X DELETE "https://sapienstream.com/api/tags/{machine_id}/{name}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/tags/statsAuth Required

Tag Statistics

Get aggregated statistics about tags across all machines.

Response

Responsejson

{
  "total_tags": 450,
  "active_tags": 425,
  "inactive_tags": 25,
  "by_datatype": {
    "REAL": 200,
    "BOOL": 150,
    "INT": 75,
    "STRING": 25
  },
  "by_quality": {
    "GOOD": 380,
    "UNCERTAIN": 30,
    "BAD": 15,
    "NULL": 25
  },
  "writable_tags": 120,
  "recent_writes": 45
}

Try it out

cURLbash

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

Batch Operations

POST/tags/batch/writeAuth Required

Batch Write Values

Write multiple tag values in a single operation for improved performance.

Request Body

Requestjson

{
  "writes": [
    {
      "machine_id": "machine_001",
      "name": "Setpoint_1",
      "value": 85.0,
      "quality": "GOOD"
    },
    {
      "machine_id": "machine_001", 
      "name": "Setpoint_2",
      "value": 75.5,
      "quality": "GOOD"
    },
    {
      "machine_id": "machine_002",
      "name": "Enable_Motor",
      "value": true,
      "quality": "GOOD"
    }
  ]
}

Response

Responsejson

{
  "success": true,
  "total_writes": 3,
  "successful_writes": 3,
  "failed_writes": 0,
  "results": [
    {
      "machine_id": "machine_001",
      "name": "Setpoint_1",
      "success": true,
      "timestamp": "2024-08-26T11:45:00Z"
    },
    {
      "machine_id": "machine_001",
      "name": "Setpoint_2", 
      "success": true,
      "timestamp": "2024-08-26T11:45:00Z"
    },
    {
      "machine_id": "machine_002",
      "name": "Enable_Motor",
      "success": true,
      "timestamp": "2024-08-26T11:45:00Z"
    }
  ]
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/tags/batch/write" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Error Responses

Common Error Codes

400 Bad Request

{
  "detail": "Invalid datatype: 'INVALID' not in ['BOOL', 'INT', 'REAL', 'STRING']"
}

404 Not Found

{
  "detail": "Tag 'NonExistent_Tag' not found on machine 'machine_001'"
}

403 Forbidden

{
  "detail": "Tag 'Temperature_Sensor_01' is not writable"
}

422 Validation Error

{
  "detail": "Value 250.0 exceeds maximum limit of 150.0 for tag 'Temperature_Sensor_01'"
}