APIs & Integrations

API Overview

Everything you need to integrate with the Optra platform — authentication, endpoints, SDKs, webhooks, and more.

The OptraIoT API provides comprehensive programmatic access to the OptraIoT platform, enabling developers to build custom integrations, manage devices, workflows, data, and machine learning models.

Overview

The OptraIoT API is built on REST principles and uses JSON for request and response payloads. It provides access to:

  • Device Management - Onboard, configure, and monitor IoT devices
  • Workflows - Create and manage automated workflows and accelerators
  • Data Management - Access and manipulate data in the platform
  • Model Hub - Manage machine learning models and experiments
  • Alerts and Notifications - Monitor and manage device alerts
  • Integrations - Connect with external systems and data sources

Base URL

https://api.optraiot.lexmark.com/api/
https://[environment].optraiot.lexmark.com/

Additional service-specific endpoints:

  • Device Management: https://api.optraiot.lexmark.com/devices
  • Workflows: https://api.optraiot.lexmark.com/workflows
  • Data Management: https://api.optraiot.lexmark.com/data
  • Model Hub: https://api.optraiot.lexmark.com/models
  • Reports: https://api.optraiot.lexmark.com/reports
  • AI Services: https://api.optraiot.lexmark.com/ai

Authentication

The OptraIoT platform supports multiple authentication methods for API access.

API Key Authentication

API keys are the primary method for programmatic API access. Each API key is tied to a specific account and provides secure authentication without exposing user credentials.

API Key Format

Authorization: bearer <api-key>

Or as a URL parameter:

?access_token=<api-key>

Creating API Keys

API keys are created through the platform:

  1. Navigate to Settings > Account > API keys
  2. Click Generate Api Key
  3. Provide:
    • Description: Describe the key's purpose (e.g., "Data import automation")
    • API Version: Select the version your integration requires
    • Expiration: Optional date for key rotation
  4. Copy the key immediately (it cannot be retrieved later)
  5. Store it securely in your application or secret management system

API Key Best Practices

  • Security: Store API keys in secure configuration or secret management systems, never in code
  • Rotation: Set expiration dates and rotate keys regularly
  • Least Privilege: Create separate keys for different integrations
  • Revocation: Delete keys immediately when compromised or no longer needed
  • Environment Isolation: Use different keys for development, staging, and production

Bearer Token Authorization

All API requests require the Authorization header:

GET /api/devices HTTP/1.1
Host: api.optraiot.lexmark.com
Authorization: bearer your-api-key-here
Content-Type: application/json

API Versioning

The OptraIoT platform supports multiple API versions to ensure backward compatibility and enable controlled deprecation of older versions.

Version Resolution

The effective API version is determined in the following order:

  1. Request Header: x-api-version header (highest priority)
  2. API Key Version: Version pinned to the API key
  3. Endpoint Default: Fallback to the default version for that endpoint

HTTP Methods

The API uses standard HTTP methods:

GET

Used to retrieve resources without modifying state.

GET /api/devices HTTP/1.1
GET /api/devices/{device-id} HTTP/1.1

POST

Used to create new resources.

POST /api/devices HTTP/1.1
Content-Type: application/json

PUT

Used to update existing resources.

PUT /api/devices/{device-id} HTTP/1.1
Content-Type: application/json

DELETE

Used to remove resources.

DELETE /api/devices/{device-id} HTTP/1.1

HTTP Status Codes

Success Codes (2xx)

  • 200 OK: Request succeeded
  • 201 Created: Resource created successfully
  • 204 No Content: Request succeeded but no content returned

Client Error Codes (4xx)

  • 400 Bad Request: Invalid request parameters or malformed JSON
  • 401 Unauthorized: Missing or invalid authentication credentials
  • 403 Forbidden: Authenticated but not authorized for resource
  • 404 Not Found: Resource does not exist
  • 409 Conflict: Request conflicts with current state
  • 422 Unprocessable Entity: Validation failed on request data

Core Concepts

Devices

Devices represent IoT and non-IoT assets monitored by the platform:

  • Device ID: Unique identifier for each device
  • Device Type: Categorization (IoT Device, Gateway, Edge Device)
  • Status: Online/Offline connectivity state
  • Telemetry: Time-series measurements from the device

Workflows and Accelerators

  • Workflow: Automated process triggered by events and conditions
  • Accelerator: Pre-built workflow templates and data processing pipelines
  • Dataset: Collection of data used by workflows

Alerts

  • Alert: Notification triggered by device conditions or workflow events
  • Severity: Critical, Warning, Normal, or Pending
  • Status: Open, Resolved, Dismissed, or Case Created

Rate Limiting

The platform enforces rate limits to ensure fair usage:

  • Per Account: 10,000 requests/hour
  • Per API Key: 5,000 requests/hour
  • Burst Limit: 100 requests/minute per API key

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4950
X-RateLimit-Reset: 1688745600

When rate limit is exceeded (HTTP 429), wait for the Retry-After header before retrying.

Error Handling

Error responses follow a standard format:

{
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "Device with ID 'invalid-id' not found",
    "statusCode": 404,
    "timestamp": "2026-06-22T14:20:00Z"
  }
}

Security Best Practices

  • API Key Storage: Store API keys in environment variables or secure vaults, never in code
  • HTTPS Only: All API requests must use HTTPS (TLS 1.2 or higher)
  • Key Rotation: Implement regular API key rotation policies
  • Request Timeouts: Always set timeouts to prevent hanging requests
  • Exponential Backoff: Implement backoff strategies for transient failures

Next Page

Authentication