Developers

Build on the asset model, not around it.

Developers integrate with PHL AI at two edges: getting readings in (files, MQTT, OPC UA via a gateway) and, later, reading twin state out through an API. This page describes the proposed design. No public API endpoints are live.

Read the documentation Integration catalogue

01Data model

Seven resources carry the twin.

Conceptual model. Field names may change before a public API is published.

Organization ─< Workspace ─< Facility ─< Area ─< Cell ─< Asset ─< Component
                                                         │
Asset ── type ──> AssetType          Asset ─< Signal ─< TelemetryRecord (time-partitioned)
Asset ─< Relationship (drives | feeds | cools | supplies | monitors) >─ Asset
Asset ── 1:1 ──> DigitalTwin ─< TwinModelVersion (immutable when published) ─< Rule
Asset ─< Alert ─< AlertEvent        Asset ─< ReviewItem        Scenario ─< SimulationRun

02Ingestion

Readings in: three paths, one pipeline.

File import

Available in MVP

Upload CSV or Parquet; map columns to signals; preview validation of the first 500 rows; background import with a row-level error file.

MQTT envelope

Requires adapter

topic: phl/{workspace}/{gateway}/telemetry
{
  "signal_key": "Cell3.P301.VibDE",
  "ts": "2026-10-14T14:20:00Z",
  "value": 4.9, "unit": "mm/s",
  "quality": "good", "seq": 18842
}

OPC UA client

Requires adapter

A gateway component subscribes to selected nodes and publishes the same envelope. It has no write or method-call capability.

Pipeline guarantees

Available in MVP

Schema validation, unit normalisation, idempotent de-duplication on (signal, timestamp, sequence), quarantine with reasons, gaps preserved.

03Planned read API

Twin state out — designed, not shipped.

The shape below illustrates the intended style. It is not a working endpoint and must not be built against.

// ILLUSTRATIVE — planned API, not available
GET /v1/assets/PMP-001/state

{
  "asset": "PMP-001",
  "twin_version": "v3",
  "state": "warning",
  "signals": [
    { "key": "vib_de", "value": 4.9, "unit": "mm/s",
      "ts": "2026-10-14T14:20:00Z", "freshness": "live" }
  ],
  "active_alerts": ["AL-0007", "AL-0010"]
}

Authentication

Planned

Workspace-scoped tokens with expiry and role-limited scopes.

Pagination & errors

Planned

Cursor pagination; problem-details JSON errors with a request ID.

Webhooks

Planned

Signed callbacks for alert opened, alert resolved and report ready.

04Adapter interfaces

Clean boundaries for new sources.

Every source implements one interface: test the connection, list available tags and read a batch. The website demo uses a mock provider that implements the same shape over bundled sample data, kept separate from any production adapter.

Integration guides in the docs →

interface TelemetrySource {
  test(): Promise<ConnectionCheck>
  listTags(): Promise<SourceTag[]>
  readBatch(since: Cursor): Promise<IngestEnvelope[]>
  // no write(): sources are read-only by design
}

Bring your industrial systems into clearer view.

Start with a focused equipment workflow and expand toward connected digital twins and industrial simulation as your requirements evolve.

Request a Demo Explore TwinCore

Illustrative demo · no signup · not connected to equipment