Ethbus documentation

API reference for integrators

System-to-system integration with Ethbus: authenticate with an API key, publish device and system events, and manage the message bus over HTTPS and JSON.

Applies to the Ethbus API host

The REST API is served by Ethbus.Api, not the web console. In local development the API listens on http://localhost:5181; production deployments expose it on your API hostname behind TLS.

Base URL

EnvironmentBase URL
Local developmenthttp://localhost:5181
Production (example)https://api.ethbus.io

All endpoints are prefixed with /api/v1. Requests and responses use application/json; charset=utf-8. Timestamps are ISO 8601 UTC.

Authentication

Every endpoint except GET /api/v1 and GET /api/v1/health requires an API key. Send it either as a custom header or as a bearer token:

X-Api-Key: eth_live_1f4c9a7be2d84c60a9158f3d7e6b2c04
Authorization: Bearer eth_live_1f4c9a7be2d84c60a9158f3d7e6b2c04

Keys are scoped to one tenant (organization). A key can read and write only that tenant's devices, flows and messages. Create keys in Console → Settings & keys; a platform administrator can audit or revoke any key. The full key is shown once — store it in your secret manager, never in source control.

401 responses

Missing API key. Send X-Api-Key (or Authorization: Bearer <key>). when no key is present, and Invalid or revoked API key. when the key does not resolve. Revocation is immediate.

Conventions

  • JSON only. Publish payloads as a JSON object. Payloads are stored and returned decoded.
  • Timestamps. occurredAt is when the event happened at the source; receivedAt is when Ethbus stored it. Omit occurredAt to default to receipt time.
  • Pagination. Message lists accept page (default 1) and pageSize (default 25, maximum 200) and return total, page, pageSize and pages.
  • Identifiers. Resource identifiers are GUIDs.
  • Priority. Low, Normal (default), High or Critical.
  • Content type. Send Content-Type: application/json on POST requests.

Errors & status codes

Errors return a JSON body with a single error string:

{ "error": "Invalid or revoked API key." }
StatusWhen it occurs
200 OKSuccessful read or action.
202 AcceptedMessage accepted for routing. The response contains the message ID and deliveries.
400 Bad RequestMissing JSON body or malformed request.
401 UnauthorizedMissing, invalid or revoked API key.
404 Not FoundMessage, device or route target not found in this tenant.
409 ConflictDelivery cannot be acknowledged because it is not in the Delivered state.

Endpoint summary

MethodPathPurposeAuth
GET/api/v1Product index and endpoint list.Public
GET/api/v1/healthLiveness, version, uptime and store path.Public
GET/api/v1/infoTenant profile, plan, counts, facilities, protocols and adapters.Key
GET/api/v1/devicesDevices with model metadata and suggested message types.Key
GET/api/v1/flowsFlows with source, destinations and transforms.Key
GET/api/v1/recommendationsExpert-system recommendations and gaps for the tenant.Key
GET/api/v1/metrics?days=14Throughput, success rate, latency and breakdowns (1–90 days).Key
GET/api/v1/alerts?open=trueOperational alerts; pass open=false to include acknowledged.Key
POST/api/v1/messagesPublish a device or system event to the bus.Key
GET/api/v1/messagesSearch the bus log with filters and pagination.Key
GET/api/v1/messages/exportDownload the filtered message log as CSV (payload included).Key
GET/api/v1/deliveries/exportDownload the delivery log as CSV (attempts, latency, errors).Key
GET/api/v1/messages/{id}Message detail with payload, flows and deliveries.Key
POST/api/v1/messages/{id}/retryReplay failed deliveries for a message.Key
POST/api/v1/deliveries/{id}/ackAcknowledge a delivered message at a destination.Key
POST/api/v1/devices/{id}/heartbeatMark a device online and update last-seen time.Key

Publish a message

POST /api/v1/messages is the primary write path. A device or system sends one event; Ethbus stores it, matches active flows and creates a delivery per destination.

Request body

FieldTypeRequiredDescription
typestringNoMessage type, for example vitals.observation. Defaults to device.event.
payloadobjectNoEvent body as a JSON object. Defaults to {}.
deviceIdguidNoRegistered device ID. Resolves facility and device metadata automatically.
sourcestringNoDevice serial or device name when deviceId is unknown; otherwise a free-form source label.
modelstringNoDevice model code when the device is not registered.
facilityIdguidNoFacility override. Defaults to the device's facility.
protocolstringNoSource protocol, for example HL7 v2, MQTT, REST/JSON. Defaults to the device protocol.
formatstringNoPayload format. Defaults to JSON.
prioritystringNoLow, Normal, High or Critical.
correlationIdstringNoCaller-defined trace identifier. Use a stable value when retrying the same event.
occurredAtdatetimeNoWhen the event occurred at the source (UTC ISO 8601).

Example

curl -X POST http://localhost:5181/api/v1/messages \
  -H "X-Api-Key: $ETHBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "3f1c2a54-8a1e-4d0b-9c77-2b6f0f9a1e42",
    "type": "vitals.observation",
    "priority": "High",
    "protocol": "HL7 v2",
    "correlationId": "obs-2026-11-0001",
    "occurredAt": "2026-11-10T08:15:00Z",
    "payload": {
      "patientId": "P-1024",
      "heartRate": 88,
      "spo2": 97,
      "temperatureC": 36.8,
      "recordedBy": "monitor-icu-04"
    }
  }'

Response · 202 Accepted

The call returns as soon as the message is stored and routed. Deliveries are queued as Pending and the delivery dispatcher sends them in the background, so poll GET /api/v1/messages/{id} for the final state.

{
  "id": "8a52d1e4-2f6b-4c1a-b9d3-7e4f0c2a6b11",
  "status": "Pending",
  "messageType": "vitals.observation",
  "sourceName": "Patient Monitor — ICU Bed 4",
  "correlationId": "obs-2026-11-0001",
  "receivedAt": "2026-11-10T08:15:02.431Z",
  "routed": true,
  "matchedFlows": 2,
  "deliveries": [
    {
      "id": "c31f6a80-0d4b-4b95-a1a7-5f2c9d6e7b02",
      "flowName": "Vitals → EMR",
      "destinationConnectorId": "6b0f9c11-6f1e-4f2b-8d7a-9e3c1b2a4d55",
      "destinationName": "OpenEMR (HL7)",
      "status": "Pending",
      "attempts": 0,
      "latencyMs": 0,
      "lastError": null,
      "deliveredAt": null,
      "ackedAt": null
    }
  ]
}

The destination itself is configured on the connector: set ConfigJson to {"endpoint": "https://host/path"} for HTTP, {"endpoint": "mllp://host:2575"} for HL7 v2, {"endpoint": "tcp://host:9000", "framing": "line"} for raw TCP, or {"endpoint": "file:C:\\drops\\lab"} for a file drop. Without a usable endpoint the delivery fails immediately with a configuration error and a Critical alert, and it is not retried.

Read the bus log

GET /api/v1/messages supports these query parameters:

ParameterDescription
statusPending, Delivered, PartiallyDelivered, Failed or NoRoute.
typeExact message type filter.
qFree-text search across source and message fields.
facilityIdRestrict to one facility GUID.
page, pageSizePagination; page starts at 1, page size is capped at 200.

Each item includes id, sourceName, sourceKind, messageType, protocol, format, status, priority, correlationId, facilityId, occurredAt, receivedAt, attempts and a deliveries count.

GET /api/v1/messages?status=Failed&type=vitals.observation&page=1&pageSize=50

For bulk archive or reconciliation, GET /api/v1/messages/export returns the same filters as a UTF-8 CSV (message ID, timestamps, source, type, status, correlation ID and payload_json). GET /api/v1/deliveries/export returns one row per flow × destination with attempts, latency and the last error. Both honour the tenant retention window.

Message detail

GET /api/v1/messages/{id} returns the message plus its decoded payload, the flows that matched, and every delivery with attempts, latencyMs, lastError, deliveredAt and ackedAt. Use this endpoint when investigating a failed or partially delivered event.

Retry & acknowledge

Retry failed deliveries

POST /api/v1/messages/{messageId}/retry
{
  "messageId": "8a52d1e4-2f6b-4c1a-b9d3-7e4f0c2a6b11",
  "retried": 1,
  "status": "replayed"
}

retried is the number of deliveries replayed. When nothing is eligible the status is nothing-to-retry. Successful deliveries are not resent.

Acknowledge a delivery

POST /api/v1/deliveries/{deliveryId}/ack
{
  "deliveryId": "c31f6a80-0d4b-4b95-a1a7-5f2c9d6e7b02",
  "acknowledged": true,
  "acknowledgedAt": "2026-11-10T08:16:10.002Z"
}

Acknowledgement records that the destination system has confirmed the event. Only deliveries in the Delivered state can be acknowledged; anything else returns 409 Conflict.

Device heartbeat

POST /api/v1/devices/{deviceId}/heartbeat
{
  "deviceId": "3f1c2a54-8a1e-4d0b-9c77-2b6f0f9a1e42",
  "status": "Online",
  "lastSeenAt": "2026-11-10T08:17:00Z"
}

Call this from each edge agent on a fixed interval (typically 30–60 seconds). It sets the device online and updates last-seen, which feeds dashboards and device-down alerts. A missing device returns 404.

Devices, flows & info

  • GET /api/v1/devices — serial, model code, model name, family, icon, edge agent, status, protocol, IP, firmware, facility and suggested message types. Use it to discover the correct deviceId and type values.
  • GET /api/v1/flows — active and inactive flows with source, destinations, message types, transform code, routing rule and priority.
  • GET /api/v1/info — tenant, plan, API key name/prefix/last-used, counts, facilities, supported protocols and adapters.

Metrics, alerts & recommendations

  • GET /api/v1/metrics?days=14 — messages, delivered, failed, noRoute, successRate, avgLatencyMs, p95LatencyMs, a daily series and breakdowns by type, source, protocol and flow. Range 1–90 days.
  • GET /api/v1/alerts?open=true — severity, category, title, detail, source, timestamps and acknowledgement state. Pass open=false for the full history.
  • GET /api/v1/recommendations — the expert engine's recommendations and gaps for the tenant, including readiness and confidence.

Message lifecycle

  1. The source posts an event to /api/v1/messages.
  2. Ethbus stores it as Pending and evaluates active flows against the message type and source.
  3. Each matching flow creates one Pending delivery per destination connector and returns 202 immediately.
  4. The delivery dispatcher claims the deliveries and sends them for real: HTTP POST, HL7 v2 over MLLP, raw TCP or a file drop, using the connector endpoint. Transient errors are retried with backoff up to Delivery:MaxAttempts; configuration errors fail at once.
  5. The message settles as Delivered, PartiallyDelivered, Failed or Pending while retries remain. A message with no matching flow is NoRoute.
  6. Operators inspect failures, fix the destination and retry. Destinations may acknowledge delivered events.
NoRoute is normal

A message with no active matching flow is stored as NoRoute, not rejected. This makes it safe to publish before a flow is activated and preserves the event for later replay.

Correlation & idempotency

  • Send a stable correlationId per real-world event. It is stored on the message and returned everywhere, so a retry at the source can be traced.
  • The API does not reject duplicate payloads; publish retries create new message records. If your source cannot guarantee exactly-once delivery, make the destination transform idempotent using the business key inside the payload.
  • Transport failures (timeouts, 5xx) are safe to retry with the same correlationId.

Code samples

C# · HttpClient

using System.Net.Http.Json;

var apiKey = Environment.GetEnvironmentVariable("ETHBUS_API_KEY");
using var http = new HttpClient { BaseAddress = new Uri("http://localhost:5181") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

var message = new
{
    type = "laundry.telemetry",
    source = "Washer 01",
    priority = "Normal",
    protocol = "MQTT",
    correlationId = $"laundry-{Guid.NewGuid():N}",
    payload = new
    {
        machineId = "W-01",
        cycle = "wash",
        waterLitres = 42.5,
        temperatureC = 38.0,
        completed = true
    }
};

var response = await http.PostAsJsonAsync("/api/v1/messages", message);
response.EnsureSuccessStatusCode();
var accepted = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(accepted.GetProperty("id").GetString());

Python · requests

import os, requests

BASE = "http://localhost:5181"
headers = {"X-Api-Key": os.environ["ETHBUS_API_KEY"]}

resp = requests.post(f"{BASE}/api/v1/messages", headers=headers, json={
    "type": "vitals.observation",
    "deviceId": "3f1c2a54-8a1e-4d0b-9c77-2b6f0f9a1e42",
    "priority": "High",
    "correlationId": "obs-2026-11-0001",
    "payload": {"patientId": "P-1024", "heartRate": 88, "spo2": 97}
}, timeout=10)

resp.raise_for_status()
print(resp.json()["id"], resp.json()["status"])

Read failures

curl -s "http://localhost:5181/api/v1/messages?status=Failed&pageSize=25" \
  -H "X-Api-Key: $ETHBUS_API_KEY"

Integration checklist

  1. Register the device or system in the console (or discover it via GET /api/v1/devices).
  2. Create an API key for the edge agent and store it securely.
  3. Confirm an active flow accepts your message type and source.
  4. Send a test event with a unique correlationId; expect 202 Accepted with routed: true.
  5. Inspect the message detail and confirm every delivery is Delivered.
  6. Add heartbeat calls and monitor metrics and alerts in staging.
  7. Handle 401 (rotate key), 404 (re-register device) and 409 (ack before delivered) explicitly in the agent.
Need the API host locally?

Run the API project on http://localhost:5181 (VS Code: Run → Ethbus API, or dotnet run --project src/Ethbus.Api). The web console runs separately on port 5180.