NOTQIN Factory API Layer Spec 2026

Purpose

Define the first NOTQIN API layer over factory data. This is inspired by HighByte’s REST Data Server / API Builder / i3X direction, but the NOTQIN version is narrower: read-only access to curated UNS data, sector-pack outputs, and signed evidence objects.

This is not an unrestricted plant-data API. It is a controlled evidence API.

Product Thesis

Moroccan exporters do not need another raw tag interface. They need a way for approved systems, auditors, customer portals, and AI agents to retrieve trustworthy operational evidence without granting broad access to the plant network.

The API layer should expose:

• current state for known assets;
• bounded historical windows;
• sector-pack KPI outputs;
• validation and data-quality status;
• signed audit/evidence objects;
• export-ready compliance packages.

It should not expose:

• PLC write commands;
• unrestricted topic wildcards;
• raw broker credentials;
• plant topology beyond the caller’s authorized scope;
• personal or sensitive data outside uns-local/#.

Non-Goals

• No write/control API in v1.
• No replacement for OPC UA, MQTT, Sparkplug B, or historians.
• No generic query over every raw tag.
• No cloud-only dependency; the API must run inside the customer droplet / local deployment.
• No LLM-direct access to raw plant data. Agents call tools that enforce scope, validation, and evidence rules.

API Surfaces

Surface	Caller	Purpose	Example
UNS browse	Factory app, integrator, support engineer	Discover authorized assets/signals.	”List all assets on Line 02 with quality signals.”
UNS read	Factory app, agent tool	Retrieve latest value or bounded time window.	”Read current temperature-c for press-01.”
KPI read	Director/QHSE dashboard	Retrieve sector-pack outputs.	”Show FPY for the last 30 days by product family.”
Evidence object read	QHSE, customer, auditor	Retrieve signed proof object and source lineage.	”Get batch evidence pack for LOT-7781.”
Audit export	QHSE, compliance module	Export compliance bundle.	”Generate IATF evidence extract for week 26.”
Health read	Plant engineer, support	Check whether data is trustworthy.	”Show connector, buffer, validator, and export health.”

Endpoint Sketch

GET /api/v1/uns/tree?site={site}&scope={scope}
GET /api/v1/uns/assets?type={asset_type}&line={line}
GET /api/v1/uns/read/latest?path={uns_path}
GET /api/v1/uns/read/window?path={uns_path}&from={iso}&to={iso}
 
GET /api/v1/kpis/oee?site={site}&from={iso}&to={iso}
GET /api/v1/kpis/fpy?site={site}&product={product}&from={iso}&to={iso}
GET /api/v1/kpis/energy-intensity?site={site}&unit={unit}&from={iso}&to={iso}
 
GET /api/v1/evidence/{evidence_id}
GET /api/v1/evidence/batch/{batch_id}
GET /api/v1/evidence/order/{order_id}
GET /api/v1/evidence/asset/{asset_id}/events?from={iso}&to={iso}
 
POST /api/v1/exports/iatf
POST /api/v1/exports/cbam
POST /api/v1/exports/as9100
 
GET /api/v1/health/data-quality
GET /api/v1/health/connectors
GET /api/v1/health/buffers

All POST /exports/* endpoints are read-only generation requests. They create an export artifact from existing evidence; they do not mutate plant state.

Evidence Object Contract

{
  "evidence_id": "ev_2026_06_30_lot_7781_fpy",
  "evidence_type": "first_pass_yield",
  "site": "ma/ma-04/stellantis-supplier/kenitra",
  "scope": {
    "batch_id": "LOT-7781",
    "order_id": "WO-2026-0148",
    "asset_ids": ["press-01", "test-stand-02"],
    "time_window": {
      "from": "2026-06-30T06:00:00Z",
      "to": "2026-06-30T14:00:00Z"
    }
  },
  "summary": {
    "status": "passed",
    "fpy_pct": 98.4,
    "defect_count": 3,
    "sample_count": 187
  },
  "source_lineage": [
    {
      "uns_path": "uns/ma/ma-04/example/kenitra/body-shop/line-02/press-01/cycle-count",
      "quality_code": "good",
      "producer_id": "edge-kenitra-line02-01"
    }
  ],
  "validation": {
    "schema_version": "morocco-uns-0.2",
    "validation_status": "valid",
    "validator_id": "sector-pack-auto-v1"
  },
  "signature": {
    "signature_alg": "ed25519",
    "producer_signature": "base64..."
  },
  "created_at": "2026-06-30T14:03:22Z"
}

Authorization Model

Map every request to a concrete scope before reading data:

Role	Allowed reads	Forbidden
plant_operator	own line/area latest values, alerts, open evidence objects	group-level financial/compliance exports
qHSE_manager	quality, batch, audit evidence for own site	raw unrestricted broker browse
plant_director	site KPIs, exports, evidence summaries	PLC write/control
integrator_support	connector health, validation failures, staging/dead-letter metadata	business evidence not needed for support
customer_auditor	explicitly shared evidence objects and exports	browse of plant topology
agent_tool	narrow tool-specific scope with deterministic validators	raw wildcard reads

Use the v0.2 identity model: mTLS for service-to-service calls, OAuth2/JWT for users, and path-prefix authorization for UNS reads.

Agent Tool Boundary

The MCP/agent layer should call this API through tools such as:

• browse_authorized_uns(scope)
• read_latest_signal(uns_path)
• query_kpi(kpi_name, filters)
• assemble_evidence_pack(evidence_type, identifiers)
• validate_evidence_object(evidence_id)
• export_compliance_pack(pack_type, scope)

The agent can propose questions and select tools. It cannot bypass validators or request raw wildcard access.

MVP Sequence

Phase	Build	Acceptance test
0	Read-only health endpoints over connectors, validators, buffers.	Plant engineer can see whether data is trustworthy before opening dashboards.
1	UNS browse/read over authorized paths.	QHSE can list available signals for one line and read bounded windows.
2	KPI read endpoints for OEE, FPY, energy intensity.	Director can retrieve 30-day KPI trend without Influx/Grafana access.
3	Evidence object API for batch, order, asset events.	One auto/aero FPY or batch evidence object can be retrieved with lineage and validation status.
4	Export generation for IATF/CBAM/AS9100.	Export artifact is reproducible from signed evidence objects.
5	MCP tool wrapper.	Agent assembles a pack through permissioned tools, not raw broker reads.

Implementation Notes

• Start inside factory-api because it already serves the deployed pilot environment.
• Read latest state from state-service where possible; use InfluxDB only for bounded historical windows.
• Use orchestrate-service health/dead-letter counters for API health endpoints.
• Keep forge-api as the site/spec source of truth; do not duplicate site configuration.
• Evidence objects should be immutable once signed. Corrections create a new evidence object that links to the superseded one.
• Every export request must log caller, scope, source evidence IDs, hash, and timestamp.

Open Questions

• Should v1 align explicitly with i3X terminology, or simply stay compatible with browse/read/subscribe concepts?
• Should evidence objects live in Postgres, object storage, or append-only files signed and indexed by Postgres?
• Which export type should ship first: IATF automotive, CBAM, or AS9100/NADCAP?
• Should customer auditors receive expiring share links or authenticated portal accounts?

Source Basis

• HighByte REST/API direction from website scrape 2026-05-27.
• HighByte i3X / factory API article from website scrape 2026-05-27.
• HighByte v4.x release signals around callable pipelines, REST Data Server, MCP Server, namespace browse/query, and federated namespaces.
• NOTQIN standards: Morocco UNS Standard v0.1 and Morocco UNS Standard v0.2 — Security & i18n.