/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

API Reference

Every service’s edge surface: HTTP as OpenAPI 3 (rendered by Swagger UI), the Socket.IO feed as AsyncAPI 3. The specs are sources in this repository, at api/*.yaml, and are published alongside this guide — so a spec change ships in the same commit as the handler it describes. They document the edge-facing surface only: internal service-to-service hops and cross-boundary payload shapes are contracts in schemas/, not public APIs.

Gateway API

claims-gateway: Keycloak login and token exchange, the session cookie, /verify for the edge.

gateway.yaml

Tenancy API

tenancy: domains, subdomains, memberships and invite codes.

tenancy.yaml

Twin API

digital-twin: building upload and status, per-domain reads, sensor placements.

twin.yaml

Telemetry API

telemetry: batch ingest, sensors, thresholds, device actions, simulation.

telemetry.yaml

Dashboard API

dashboard: the metric catalog and each building’s column preferences.

dashboard.yaml

Notification API

notification: Web Push subscriptions, alert switches, manual alerts.

notification.yaml

Chat API

chat: conversations, and answers streamed as Server-Sent Events.

chat.yaml

Agent API

agent: ask the assistant, ingest documents. Generated from the FastAPI app.

agent.yaml

Socket API

socket: the live Socket.IO feed — notifications, telemetry ticks, device dots, building subscriptions.

socket.yaml · AsyncAPI

Common Error Responses

The error bodies each stack sends, referenced by the specs above.

error.yaml

socket.yaml is AsyncAPI 3, not OpenAPI: Socket.IO pushes events instead of answering requests, so it opens in its own viewer (api/asyncapi.html). registry and provisioner have no edge route, so they have no card.