Telemetry Ingestion API

AudienceIntegrators, OT/IT Engineers

Required PermissionsActive Telemetry API Key for the target plant

Estimated Time6 min read

Demo Referencecemento-valladolid

Use the Telemetry API (telemetry-api) to push real-time sensor readings into an OTCognix plant.

Endpoint

POST /api/v1/ingest/iot-data

Authentication

Use HTTP Basic Authentication with your plant Telemetry API Key (key as username, secret as password). Plant and company scope are derived exclusively from the authenticated credential—never from the request body.

Request Payload

Field	Type	Description
timestamp	integer	Positive Unix epoch timestamp in milliseconds when the batch was sent.
values	array	Non-empty list of sensor readings (id, v, q, t).
values[].id	string	Source Tag identifier (non-empty string).
values[].v	number	Numeric measurement value.
values[].q	boolean	Quality flag (true = Good, false = Bad).
values[].t	integer	Sensor recording timestamp (Unix epoch in milliseconds).

{
  "timestamp": 1754802764766,
  "values": [
    {
      "id": "CDEMO.CM01.CIR001.FRESH_FEED",
      "v": 60.41,
      "q": true,
      "t": 1754802759166
    }
  ]
}

Responses

• 201 Created: Batch accepted and queued in Redis Streams (includes rejected tags if any).
• 401 Unauthorized: Missing, invalid, or inactive credentials.
• 422 Unprocessable Entity: Invalid payload or no usable tags.
• 429 Too Many Requests: Publish rate gate triggered (check Retry-After).
• 503 Service Unavailable: Credential or storage outage (Retry-After: 5).
• 500 / 504: Unexpected error or downstream timeout.

Delivery Semantics

A 201 response confirms Redis ingestion, not downstream TimescaleDB persistence. If a 503 occurs mid-batch, partial writes may already be persisted—retry with at-least-once semantics.