Developer APIs
One governed data contract for the whole estate.
PrecisionDCOS exposes read, streaming, command, export and webhook APIs over a common data contract. Every value carries identity, time, quality, authority and evidence — so what you build on it stays trustworthy.
The common data contract
Every value published by the platform is self-describing and governed — not a bare number on a topic.
Identity, time, quality, authority, evidence
A value is never delivered alone. It arrives with where it came from, when it was true, how much it can be trusted, whether it can be acted on, and the evidence trail behind it. This contract is what lets operations and AI act on the data without re-deriving trust every time.
API families
Governed surfaces mapped to the DCOS Data Fabric resource families, all sharing the same identity, tenancy and evidence model. Command is disabled by default.
- Assets & dependencies
- Read sites, systems, assets, services and their relationships — the identity graph the rest of the API keys against.
- Telemetry & state
- Query current and historical quality-aware values and operational state, tenant-scoped and residency-governed.
- Events & incidents
- Read lifecycle events, alarms, incidents and their correlations; subscribe to governed real-time streams with backpressure and replay.
- Work & change
- Read work orders, changes, maintenance and approvals linked to the events that generated them.
- Evidence & reports
- Retrieve linked control records and generated assurance packages with identity, time and authority intact.
- Export & publication
- Publish governed datasets to lakes, warehouses and AI pipelines with lineage and quality preserved (async for large windows).
- Webhooks
- Receive signed callbacks on incidents, state changes and closure with linked evidence references and idempotency keys.
- Command (disabled by default)
- Bounded, fenced action requests through engineered command paths. Off unless explicitly enabled per tenant, and never a bypass of protective controls.
Data quality is a first-class field
Every value carries an explicit quality state so consumers never act on data they cannot trust.
Value is trusted and within expected behavior.
Value is questionable; confidence is reduced.
Value is invalid and must not drive action.
Value has not updated within its expected interval.
Point is intentionally removed from active monitoring.
Value is injected for test and clearly flagged as non-live.
Example payloads
A point read, an event read and an async dataset export — each showing the full governed contract.
GET /api/v1/points/{id}/value
{
"point": "site-04.chw.loop-a.supply-temp",
"value": 7.2,
"unit": "degC",
"timestamp": "2026-08-07T14:22:05.118Z",
"quality": "GOOD",
"identity": {
"site": "site-04",
"domain": "mechanical",
"asset": "chiller-plant-a"
},
"authority": {
"class": "monitor",
"commandable": false
},
"evidence": {
"source": "nx-node-2",
"collector": "bacnet-collector-11",
"trace": "ev_9f2c81a4"
}
}GET /api/v1/events/{id}
{
"event": "evt_5b71c0",
"type": "incident",
"severity": "major",
"state": "open",
"opened": "2026-08-07T14:22:06.004Z",
"identity": {
"site": "site-04",
"asset": "chiller-plant-a",
"service": "cooling-loop-a"
},
"correlation": ["evt_5b7180", "evt_5b7166"],
"authority": { "class": "monitor", "commandable": false },
"evidence": { "trace": "ev_9f2c81a4", "records": ["wo_44121"] }
}POST /api/v1/exports
{
"dataset": "telemetry.chw",
"contract": "v2",
"window": { "from": "2026-08-01", "to": "2026-08-07" },
"format": "parquet",
"residency": "us",
"delivery": { "mode": "async", "target": "s3://tenant-bucket/exports" }
}
// 202 Accepted
{
"export": "exp_7c19",
"status": "queued",
"poll": "/api/v1/exports/exp_7c19"
}Access & governance
APIs are governed the same way the platform is — scoped identity, explicit authority, versioned contracts and full auditability.
- Authentication
- OAuth 2.0 / OIDC for interactive and service identities; mTLS for machine-to-machine at the edge.
- Tokens & tenancy
- Short-lived, tenant-scoped, least-privilege access tokens; every call is bound to a single tenant.
- Versioning
- URI-versioned under /api/v1; dataset contracts are independently versioned (e.g. contract v2).
- Pagination
- Cursor-based pagination on list endpoints with stable ordering.
- Async export
- Large exports are asynchronous — submit, receive 202 + poll URL, then collect from governed delivery.
- Idempotency
- Mutating and webhook-delivered operations accept idempotency keys so retries never double-apply.
- Rate controls
- Per-tenant, per-surface rate limits with standard rate-limit headers and backpressure on streams.
- Audit
- Every request and action is audited with linked evidence and residency-aware retention.
Frequently asked questions
Common questions about authority, trust and consuming the API.
- Can the API change equipment?
- Not by default. Command APIs are disabled per tenant unless explicitly enabled, and even then every action passes through the same published command, local validation, authority, interlock, expiration, feedback and audit requirements as any other equipment-changing request. Read, streaming and export surfaces never actuate anything.
- How is a value trusted?
- Every value is self-describing: it carries identity, source/receipt time, an explicit quality state, an authority class (monitor by default) and an evidence trace. Consumers reason on the quality field rather than assuming a bare number is good.
- How do dataset contracts version?
- Each resource family publishes against a versioned dataset contract — declared fields, units, quality semantics and identity keys. Contracts version independently of the /api/v1 URI so a schema evolution does not silently break existing consumers.
- How do large exports work?
- Submit an export request and receive 202 Accepted with a poll URL. The job runs asynchronously and delivers to governed object storage under residency policy; you poll the URL for status rather than holding a long request open.
Build on governed data
Request API documentation and a sandbox scoped to a reference environment.