API reference

Authentication

Sign in with username and password; you get a signed HS256 JWT to send as a bearer token on every subsequent request. Tokens last roughly ten hours and there is no refresh token — re-authenticate on a 401.

curl -s -X POST https://your-host/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"..."}'

# → { "username": "admin", "roles": ["ROLE_ADMIN"], "access_token": "eyJ..." }

curl -s https://your-host/graphql \
  -H 'Authorization: Bearer eyJ...' \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ me { id username } }"}'

GraphQL

POST /graphql, authenticated. In development a GraphiQL explorer is served at /graphiql, which is the fastest way to discover the schema — it is generated partly from your own domain model.

Auto-generated CRUD

Domain classes that declare a GraphQL mapping get queries, paginated list queries and create / update / delete mutations generated for them. That covers devices, ports, peripherals, cables, zones, layers, racks, patch panels, jobs, scenarios, users, roles, categories and configuration entries.

query {
  devicePeripheralList(max: 20, sort: "name") {
    id
    name
    category { name }
    zones { id name }
    connectedTo { id internalRef state value }
  }
}

Custom queries

Custom mutations

Switching something

Control does not go through an auto-CRUD update on the port row — it goes through the event bus, so zone expansion, device confirmation and audit logging all apply.

mutation {
  pushEvent(input: {
    p0: "evt_switch"
    p1: "PERIPHERAL"
    p2: "1042"
    p3: "api"
    p4: "ON"
  }) { success }
}

Use p1: "ZONE" to switch everything in an area, recursively, or p1: "PORT" to address a single I/O line.

Voice

mutation {
  voiceCommand(transcript: "turn off everything on the terrace",
               locale: "en", sessionId: "abc123") {
    reply
    awaitingReply
    sessionId
    audioContent     # base64 MP3, when neural TTS is enabled
  }
}

Keep the returned sessionId and pass it back to continue a conversation. awaitingReply is true only when nothing was actioned and the reply is a question — the client uses it to reopen the microphone.

REST endpoints

WebSocket

Live state arrives over STOMP on WebSocket — not GraphQL subscriptions. Clients authenticate, subscribe, and receive port-value and device-status changes as they happen, which is why two phones and a wall tablet stay in agreement without polling.

The public shared-link pages are the exception: no authenticated socket, so they re-read state after each action.

MQTT

The device-facing API. myHAB subscribes to myhab/# (plus the ONVIF bridge prefix) and routes inbound messages by matching them against per-model patterns. Full topic contracts are in Integrations → MQTT topic contracts.

# command a relay
mosquitto_pub -t 'myhab/esp_terrace/relay/3/cmd' -m 'ON'

# watch everything
mosquitto_sub -t 'myhab/#' -v

A useful side door: any source can raise an in-app message by publishing to myhab/<source>/notify. That is how a script on another machine can put something in the inbox without touching the HTTP API.

Errors and conventions

• GraphQL mutations return a response object with a success flag and messages rather than throwing for expected failures.
• REST errors use conventional status codes: 400 malformed, 401 unauthenticated, 403 not permitted or an unusable state, 404 unknown.
• Timestamps are milliseconds since epoch, UTC.
• Ids are strings in GraphQL (ID) even though they are numeric in the database.
• Publishing an event is fire-and-forget: a success means the command was accepted and published, not that the device confirmed it.