API Overview

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 its subdomain (https://{slug}.consystence.com, or {slug}.consystence.dev for Integrator tenants and sandboxes); a site server serves the same surface at its own address. This is the canonical programmatic surface — what external integrations and the CLI call (the tenant 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 tenant subdomain or, on a site server, at the server’s own address. 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 and PLCnext today), tags, device instances, the electrical model, and data subscriptions.
Operations	operational reads, alarm acknowledgement, historian ingest, AI endpoints	Read live operational state (instance tag values, historian trend windows, active alarms and alarm history, the command-audit ledger), acknowledge alarms, 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/*). No REST endpoint writes a tag value or issues a plant command.
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 org-scoped config keys (an org owner or admin) and, on a site server, the server’s own configuration store (the site’s administrators).
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 and factory reset on a site server. The cloud’s provision endpoints serve Consystence’s account service and site-server activation, not API clients.

AI is advisory-only

The AI endpoints — the site-facing /api/ai group and the cloud proxy (/api/cloud/ai/*) — have no path to equipment: AI reads, explains and recommends; it never commands equipment. No REST endpoint writes a tag value or issues a plant command. A command is issued only by a person: from the operator console, or with an operator API key that acts for one person on one native site. The AI can propose a command but never issue it. A command takes a confirmation step wherever it requires one, and every command is audited. 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 redirects to the account’s organisation list with a tenant-suspended notice.
POST /api/provision	Sandbox provisioning into {slug}.consystence.dev: 200 provisioned or already provisioned, 202 accepted but not yet active (the sandbox appears in GET /api/tenants once it is active), 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, requests for a paid tier (arranged with our team), invites, member removal, and org-scoped provisioning.

Public beta

The hosted service is in public beta. During the beta, free individual sandboxes and paid organisations are both arranged with our team: request access. See tenant provisioning for the end-to-end flow.

Authentication

The in-cell surface accepts three credentials, and the server chooses how to validate a request from the credential it carries. In brief:

• Organisation sign-in (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). A key is read-only by default; an operator key acts for one person on one native site. See API keys.
• Site-PIN token — issued by a site server for offline-capable sign-in at the site, and accepted by site servers only; the hosted service does not accept it.

Sign-up, passwords, second factors and credential recovery for the organisation account are handled by the identity provider (Entra External ID); the Consystence server has no email/password sign-in, no switch-org endpoint and no refresh endpoint for organisation sign-in tokens. Platform administration is a Consystence operations capability, not a licence authority. How each credential is validated, and the token flows, are covered in the authentication model.

Note

The published OpenAPI document declares two security schemes, Bearer and ApiKey, and lists on each operation the ones it accepts. It notes where an API key is limited: a read-only key only reads, an operator key acts only on its one site, and some reads need an owner or admin role. API keys gives the full rules. The credential model and token flows are documented in the auth-model guide.

Conventions

Versioning

The in-cell surface is unversioned; the generated OpenAPI document reports, as its version, the product revision it was exported from (1b6c536f3). 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. Some endpoints (for example a failed tenant export, import or restore) 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 covers the cell-direct endpoints the CLI and its client library call, exported on 21 October 2026 from the revision the hosted service was running, with each path’s verbs, tags, request schemas and the credentials each accepts. It does not describe status codes or response bodies (every operation shows a generic 200); the guides give those where they matter, for example the 201 response when you mint a key. Operations that only a site server serves, and those that only the hosted service serves, are marked. Platform-operator and server-to-server endpoints are not part of the public reference.

Caution

The OpenAPI document is auto-generated from the server via Swashbuckle and annotated at export with the credentials each operation accepts and where it is served; other annotations are sparse. Expect an endpoint-level surface (paths, methods, tags and request schemas, as of the export date) with no response schemas and few human-written summaries. 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 credentials a client sends and how each is validated.
• 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.
• Site activation — linking a site server to its hosted tenant with a one-time code.