APIs & Integrations

SDKs

Official Optra client libraries for JavaScript, Python, and other languages.

The OptraIoT platform provides software development kits (SDKs) to help developers integrate with the platform and build applications programmatically.

Python SDK

The OptraIoT Python SDK provides a comprehensive Python client for interacting with the OptraIoT platform. It allows you to manage devices, workflows, accelerators, datasets, and ML models programmatically.

Installation

The Python SDK is available as a package called optraiot. You can install it using pip:

pip install optraiot

Core Components

Authentication

The SDK uses API key-based authentication to secure requests to the OptraIoT platform.

ApiKey Class

from optraiot import ApiKey

auth = ApiKey("your-api-key-here")

The ApiKey class handles authentication credentials and provides:

  • to_params(): Converts the API key to URL parameters for API requests
  • authorization_header(): Generates the authorization header value in bearer token format

Device Management Service

Manage and interact with IoT devices in the OptraIoT platform.

DeviceManagementService Class

from optraiot import ApiKey, DeviceManagementService

auth = ApiKey("your-api-key")
device_service = DeviceManagementService(auth, "https://api.optraiot.lexmark.com")

Key Methods:

  • list_device(device_id) - Get a single device by ID
  • list_devices() - List all available devices
  • list_devices_url() - Get the URL for the devices endpoint
  • generate_device_alert(device_id, webhook_key, alert_data) - Generate an alert for a device

Example - Retrieve a Device:

device = device_service.list_device("device-id-123")

Workflow Service

Manage workflows, accelerators, datasets, and visualizations in the OptraIoT platform.

WorkflowService Class

from optraiot import ApiKey, WorkflowService

auth = ApiKey("your-api-key")
workflow_service = WorkflowService(auth, "https://api.optraiot.lexmark.com")

Key Methods:

Accelerators:

  • list_accelerators() - Get a list of all accelerators
  • get_accelerator(accelerator_id) - Get an accelerator by ID
  • create_accelerator(**params) - Create a new accelerator

Datasets:

  • list_datasets() - Get a list of all datasets
  • get_dataset(dataset_id) - Get a dataset by ID
  • create_dataset(**params) - Create a new dataset

Model Hub

Interact with machine learning models in the OptraIoT platform.

The Model class supports:

  • Model management and parameter configuration
  • Experiment creation and tracking
  • Model execution and result retrieval
  • WebSocket connections for real-time communication

Usage Examples

Example 1: Basic Setup and Device Retrieval

from optraiot import ApiKey, DeviceManagementService

# Initialize authentication
auth = ApiKey("aN3c99fERYimiEeC3Ef2RUbqhxVzKBwf1cGoQjJN3YJQgMjFOLBNViQDTn444gty")

# Create device management service
device_service = DeviceManagementService(auth, "https://api.optraiot.lexmark.com/devices")

# Retrieve a device
device = device_service.list_device("b0c407fb-7da5-4727-b2fd-80ac968045b6")

Example 2: Multiple Services

from optraiot import ApiKey, DeviceManagementService, WorkflowService

auth = ApiKey("your-api-key")

# Initialize services
device_service = DeviceManagementService(auth, "https://api.optraiot.lexmark.com/devices")
workflow_service = WorkflowService(auth, "https://api.optraiot.lexmark.com/workflows")

# Retrieve devices and accelerators
devices = device_service.list_devices()
accelerators = workflow_service.list_accelerators()

Example 3: Device Alerts

from optraiot import ApiKey, DeviceManagementService

auth = ApiKey("your-api-key")
device_service = DeviceManagementService(auth, "https://api.optraiot.lexmark.com/devices")

# Generate a device alert
alert_data = {
    "status": "critical",
    "alert_code": "high_temperature",
    "component": "processor",
    "temperature": 95
}

device_service.generate_device_alert(
    device_id="device-id-123",
    webhook_key="webhook-key-xyz",
    alert_data=alert_data
)

Device Client Library

For IoT devices and edge applications, OptraIoT provides a lightweight device client library.

OptraIoT Device Client

The device client is a lightweight library for sending telemetry and alerts from devices or edge applications to the OptraIoT platform.

Installation:

pip install optraiot

Initialization:

from optraiot import OptraIoT

# Initialize from environment variables or parameters
client = OptraIoT(
    endpoint="https://optraiot.lexmark.com/devices",
    key="your-webhook-key",
    device_id="your-device-id"
)

The client supports configuration via environment variables:

  • OPTRAIOT_ENDPOINT - API endpoint URL
  • OPTRAIOT_KEY - Webhook key for authentication
  • OPTRAIOT_DEVICE_ID - Device ID
  • IOTEDGE_DEVICEID - Alternative device ID source

Sending Telemetry:

from optraiot import OptraIoT

client = OptraIoT()

# Send telemetry data
message = {"temperature": 72.5, "humidity": 45}
success = client.send(
    message=message,
    message_type="telemetry",
    component="sensor_1",
    device_metadata={
        "name": "Sensor Device",
        "location": "Building A",
        "geocoordinates": [38.0283, -84.4716],
        "serial_number": "SN123456"
    }
)

if success:
    print("Message sent successfully")

Sending Alerts:

from optraiot import OptraIoT

client = OptraIoT()

# Send an alert
success = client.log(
    state="critical",
    alert_code="temperature_exceeded",
    message="Temperature exceeds safe threshold",
    component="thermal_zone",
    metadata={"temperature": 85}
)

SDK Dependencies

The Python SDK requires the following dependencies:

  • requests>=2.31,<3 - HTTP library
  • urllib3<3 - HTTP client
  • charset-normalizer>=2,<4 - Character encoding detection
  • chardet<6 - Character encoding detection
  • websocket-client - WebSocket support for real-time communication

API Response Handling

The SDK automatically handles API responses based on content type:

  • JSON responses - Parsed and returned as Python dictionaries
  • Text responses - Returned as strings
  • Binary content - Returned as raw bytes
  • Empty responses - Returns None

Error Handling

The SDK raises RuntimeError exceptions for API errors:

try:
    device = device_service.list_device("invalid-id")
except RuntimeError as e:
    print(f"API Error: {e}")

Supported API Endpoints

The Python SDK provides access to the following API categories:

  1. Device Management - Create, retrieve, update, and manage devices
  2. Workflows - Manage workflows, accelerators, and datasets
  3. Model Hub - Manage ML models, experiments, and executions
  4. Alerts - Generate device alerts and manage notifications

Version Information

  • Current Version: 11.0
  • Package Name: optraiot
  • License: MIT

Getting Started

To get started with the OptraIoT Python SDK:

  1. Install the SDK: pip install optraiot
  2. Obtain an API key from the OptraIoT platform
  3. Initialize the authentication: auth = ApiKey("your-api-key")
  4. Create a service instance (Device Management, Workflow, or Model Hub)
  5. Use the service methods to interact with the platform

Support and Documentation

For additional information and support:

  • Refer to the OptraIoT platform for API documentation
  • Check the Python SDK source code for detailed method signatures
  • Review the examples included in the SDK package
  • Contact the OptraIoT support team for assistance

Previous Page

Response Examples

Next Page

Webhooks