Reference

API Reference

The IIOS HTTP API is a stable, versioned interface onto the operating system. Every request is scoped to your tenant and sovereignty boundary, and every response carries provenance and a calibrated confidence score.

Base URL & versioning

All endpoints are served under a versioned prefix. Breaking changes ship under a new version; additive changes do not.

Base URL

https://api.iios.dev/v1

Authentication

Requests authenticate with a bearer token and a tenant header. Tokens are scoped service credentials that inherit the platform permission model — they can never exceed the access of the principal that issued them.

Terminal

curl https://api.iios.dev/v1/graph/status \
  -H "Authorization: Bearer $IIOS_TOKEN" \
  -H "X-IIOS-Tenant: acme-industrial"

Endpoints

The core surface is small and composable. Graph, reasoning, agents, and webhooks share one consistent request and response shape.

POST/v1/graph/query

Query and traverse entities, relationships, events, and evidence.

POST/v1/graph/mutate

Assert entities, relationships, and events with attached evidence.

POST/v1/reason

Run an evidence-linked reasoning query scored by the Confidence Engine.

POST/v1/agents/{id}/invoke

Invoke a scoped agent; every step is recorded as an immutable event.

GET/v1/webhooks

List webhook subscriptions for graph and reasoning events.

Query the graph

The graph query endpoint accepts a declarative body describing what to match and what to traverse.

Request

POST /v1/graph/query
Authorization: Bearer $IIOS_TOKEN
X-IIOS-Tenant: acme-industrial
Content-Type: application/json

{
  "type": "Asset",
  "where": { "site": "PLANT-04", "status": "degraded" },
  "traverse": { "events": { "since": "-90d" }, "evidence": true },
  "limit": 50
}

Parameters

Field	Type	Required	Description
type	string	Yes	Ontology entity type to query, e.g. "Asset".
where	object	No	Attribute filters applied to matched entities.
traverse	object	No	Relationships, events, and evidence to expand.
limit	integer	No	Max entities per page. Default 25, max 500.
cursor	string	No	Pagination cursor from a prior response.

Response

200 OK

{
  "entities": [
    {
      "id": "asset:pump-1183",
      "type": "Asset",
      "attributes": { "site": "PLANT-04", "status": "degraded" },
      "confidence": 0.94,
      "evidence": [
        { "source": "scada:PLANT-04", "ts": "2025-06-30T14:02:00Z" }
      ]
    }
  ],
  "page": { "next": "eyJvIjo1MH0", "total": 128 }
}

Errors

Errors use standard HTTP status codes with a machine-readable body. 401 for invalid credentials, 403 when access is denied by policy, 422 for malformed queries, and 429 when rate limited.

Documentation SDK guides