API Reference

Consystence exposes two HTTP surfaces, differing in audience and addressing:

• The in-cell server API — /api/... served cell-direct from a tenant’s own cell at https://{org}.consystence.com. This is the canonical programmatic surface — what external integrations, the SDK, and the CLI call (the org subdomain CNAMEs straight to the cell). It covers site setup and activation, the controller/tag engineering model, historian ingest, and tenant administration.
• The account control-plane API — /api/... at https://account.consystence.com: account identity, tenant listing and routing hand-off, sandbox provisioning, and org management. See below.

The in-cell API is served by the Consystence server — one codebase published as either a cloud organisation/cell manager or an on-premises site server (the mode is baked into the artifact at publish time); which endpoints are active depends on the mode. For how the platform is organised into accounts, cells, orgs, and sites, see the platform overview and org & site model.

flowchart LR
  Client["API client<br/>(browser, CLI, integration)"]
  Srv["In-cell server API<br/>{org}.consystence.com/api/..."]
  Acc["Account control plane<br/>account.consystence.com/api/..."]
  Client -->|"Authorization: Bearer / X-Api-Key csk_*"| Srv
  Client -->|"Authorization: Bearer"| Acc

There is no separate public gateway host

An earlier design placed a versioned public gateway at api.consystence.com/v1. It was retired before it was ever deployed: the cell-direct /api surface is the canonical programmatic entry point, and the CLI is the supported public client. A versioned public API may return later as a deliberate new product decision. See the public API surface.

The in-cell server API

Everything under /api/... (plus /auth/... and /.well-known/jwks.json) is the server’s own surface, reached directly at the org subdomain {org}.consystence.com. It is grouped roughly as follows:

Area	Endpoint groups	Purpose
Engineering model	sites, controllers, datapoints, controller tag management, instances, electrical, subscriptions	Define sites, controllers (ControlLogix / PLCnext / Modbus), tags, device instances, the electrical model, and data subscriptions.
Operations	edge commands, operational reads, historian ingest, AI endpoints	Issue edge commands, read live operational state (instance tag values, historian trend windows, active alarms, the command-audit ledger), ingest historian/model data into a cell, and serve AI completions (the site-facing /api/ai group — health and completions — plus the cloud proxy /api/cloud/ai/*).
Tenant administration	admin/orgs, members, domains, admin/api-keys, sync keys	Manage organisations, memberships and roles, domain bindings, and API keys. Licence state is read inline on the org detail; issuance lives in the account console.
Configuration	admin/config, admin/orgs/{slug}/config	The audited platform config store (platform-admin: list, set/unset by key, audit trail, reload) and the org-scoped config keys (gated on the org’s own owner/admin).
Identity & session	auth/login, auth/callback, auth/token, auth/logout, jwks.json	Interactive login/callback and session token issuance. OIDC discovery is consumed, not served.
Lifecycle	setup/status, setup/site-activation, setup/reset, provision	Setup status, code-keyed site activation, factory reset, and org provisioning (account → cell).

AI is advisory-only

The AI endpoints — the site-facing /api/ai group and the cloud proxy (/api/cloud/ai/*) — and the edge command and tag-write endpoints exist on the same surface, but they are not connected: AI configures, queries, classifies, and explains — it never commands equipment. Hard interlocks live in IO modules and safety relays, not in the API.

The account control-plane API

The account service at https://account.consystence.com exposes its own small JSON API — the machine seam behind the account console and the CLI’s account context (see the CLI). Callers authenticate as the CIAM account identity (keyed on the Entra oid):

Endpoint	Purpose
GET /api/me	The signed-in account’s profile.
GET /api/tenants	The account’s tenants — slug, canonical domain, org type, and status (never a cell host).
GET /route?tenant={slug}	Hand-off to a tenant’s own host: 302 to the canonical domain; 404 when the account has no (or no such) tenant; 409 with a tenant list when ambiguous; a suspended tenant bounces to the billing surface.
POST /api/provision	Self-serve sandbox provisioning into {slug}.consystence.dev: 200 provisioned or already provisioned, 202 accepted — pending operator approval ({"status":"pending_approval"}), 400 invalid or reserved slug, 409 slug conflict or quota ceiling, 429 rate-limited, 402 entitlement denied, 502 upstream failure (the intent is durable — a retry resumes idempotently).
/api/orgs/*	Org management: create/list orgs, org detail and licences, tier requests, invites, member removal, and org-scoped provisioning.

Note

The account control plane runs in production and provisions organisations onto the enrolled production cell. Self-serve signup remains behind launch gates: a new-tenant request awaits operator approval (the 202 pending outcome above) before it is provisioned. See tenant provisioning for the end-to-end flow.

Authentication

The in-cell surface sits behind a single multi-scheme selector (“MultiAuth”) that picks an authentication handler per request. In brief, the schemes are:

• CIAM Bearer — Entra External ID tokens from id.consystence.com (Authorization: Bearer …). The stable membership key is the Entra oid; email is a verified attribute, not the identity.
• X-Api-Key — tenant API keys, prefix csk_, minted at POST /api/admin/api-keys (shown in plaintext once). See API keys.
• Locally-issued JWT — site-PIN tokens for offline-capable on-premises sites.
• TestScheme — test-only.

There is no email/password sign-in, no /register, no MFA or switch-org endpoint, and no refresh for CIAM. Platform-admin is a Consystence-staff role, not a licence authority. The full selector, policies, and token flows are covered in the authentication model.

Note

The published OpenAPI document declares the security schemes (Bearer, ApiKey, SyncApiKey) with per-operation requirements; the conceptual model, policies, and token flows are documented in the auth-model guide.

Conventions

Versioning

The in-cell surface is unversioned; the generated OpenAPI document currently reports v0.1. A versioned public API surface may be introduced later as a deliberate product decision — there is none today.

Error shape

Errors are a flat JSON object with a single error string — not RFC 7807 ProblemDetails:

{ "error": "Device instance 'PP-01' already exists at site 'pit-1'" }

Some endpoints attach extra context fields alongside error (for example a list of missing IDs); successful action endpoints may return { "message": "…" }. Status codes follow HTTP convention: 400 validation, 401/403 auth, 404 not found, 409 conflict. A handful of operator endpoints (for example org re-bootstrap conflicts) return RFC 7807 problem responses instead — treat the flat error object as the convention, not an invariant.

Identifiers

Sites are addressed by their code as a path segment (/api/sites/{code}) — a site is a path under the org, never its own domain. Device types use reusable dotted IDs (consystence.pump.centrifugal); device instances are per-site and carry an asset number (PP-01). See the type system.

The full reference

The machine-generated endpoint list is published as rendered OpenAPI at /api/reference/. It is CLI-scoped: it documents the supported public (CLI-exposed) endpoint surface — the paths the CLI drives — with each path’s verbs, tags, and request/response schemas. Server-to-server and operator-internal endpoints are documented in the companion guides instead.

Caution

The OpenAPI document is auto-generated from the server via Swashbuckle, and the source annotations are sparse. Expect an accurate, endpoint-level surface (paths, methods, tags, and the request/response model schemas) but few human-written summaries or per-status descriptions. The companion guides below add the prose the spec omits.

Guides

For task-oriented depth, start with the guide that matches your goal:

• Authentication model — the MultiAuth selector, schemes, and policies.
• API keys — minting and using csk_ tenant keys.
• Public API surface — why the API is cell-direct and there is no separate gateway host.
• Historian — ingesting and querying time-series data.
• Provisioning — the account → cell org provisioning contract.