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
| Environment | Base URL |
|---|---|
| Local development | http://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.
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.
occurredAtis when the event happened at the source;receivedAtis when Ethbus stored it. OmitoccurredAtto default to receipt time. - Pagination. Message lists accept
page(default 1) andpageSize(default 25, maximum 200) and returntotal,page,pageSizeandpages. - Identifiers. Resource identifiers are GUIDs.
- Priority.
Low,Normal(default),HighorCritical. - Content type. Send
Content-Type: application/jsonon POST requests.
Errors & status codes
Errors return a JSON body with a single error string:
{ "error": "Invalid or revoked API key." }
| Status | When it occurs |
|---|---|
200 OK | Successful read or action. |
202 Accepted | Message accepted for routing. The response contains the message ID and deliveries. |
400 Bad Request | Missing JSON body or malformed request. |
401 Unauthorized | Missing, invalid or revoked API key. |
404 Not Found | Message, device or route target not found in this tenant. |
409 Conflict | Delivery cannot be acknowledged because it is not in the Delivered state. |
Endpoint summary
| Method | Path | Purpose | Auth |
|---|---|---|---|
GET | /api/v1 | Product index and endpoint list. | Public |
GET | /api/v1/health | Liveness, version, uptime and store path. | Public |
GET | /api/v1/info | Tenant profile, plan, counts, facilities, protocols and adapters. | Key |
GET | /api/v1/devices | Devices with model metadata and suggested message types. | Key |
GET | /api/v1/flows | Flows with source, destinations and transforms. | Key |
GET | /api/v1/recommendations | Expert-system recommendations and gaps for the tenant. | Key |
GET | /api/v1/metrics?days=14 | Throughput, success rate, latency and breakdowns (1–90 days). | Key |
GET | /api/v1/alerts?open=true | Operational alerts; pass open=false to include acknowledged. | Key |
POST | /api/v1/messages | Publish a device or system event to the bus. | Key |
GET | /api/v1/messages | Search the bus log with filters and pagination. | Key |
GET | /api/v1/messages/export | Download the filtered message log as CSV (payload included). | Key |
GET | /api/v1/deliveries/export | Download 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}/retry | Replay failed deliveries for a message. | Key |
POST | /api/v1/deliveries/{id}/ack | Acknowledge a delivered message at a destination. | Key |
POST | /api/v1/devices/{id}/heartbeat | Mark 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
| Field | Type | Required | Description |
|---|---|---|---|
type | string | No | Message type, for example vitals.observation. Defaults to device.event. |
payload | object | No | Event body as a JSON object. Defaults to {}. |
deviceId | guid | No | Registered device ID. Resolves facility and device metadata automatically. |
source | string | No | Device serial or device name when deviceId is unknown; otherwise a free-form source label. |
model | string | No | Device model code when the device is not registered. |
facilityId | guid | No | Facility override. Defaults to the device's facility. |
protocol | string | No | Source protocol, for example HL7 v2, MQTT, REST/JSON. Defaults to the device protocol. |
format | string | No | Payload format. Defaults to JSON. |
priority | string | No | Low, Normal, High or Critical. |
correlationId | string | No | Caller-defined trace identifier. Use a stable value when retrying the same event. |
occurredAt | datetime | No | When 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:
| Parameter | Description |
|---|---|
status | Pending, Delivered, PartiallyDelivered, Failed or NoRoute. |
type | Exact message type filter. |
q | Free-text search across source and message fields. |
facilityId | Restrict to one facility GUID. |
page, pageSize | Pagination; 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 correctdeviceIdandtypevalues.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, adailyseries 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. Passopen=falsefor the full history.GET /api/v1/recommendations— the expert engine's recommendations and gaps for the tenant, including readiness and confidence.
Message lifecycle
- The source posts an event to
/api/v1/messages. - Ethbus stores it as Pending and evaluates active flows against the message type and source.
- Each matching flow creates one Pending delivery per destination connector and returns
202immediately. - 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. - The message settles as Delivered, PartiallyDelivered, Failed or Pending while retries remain. A message with no matching flow is NoRoute.
- Operators inspect failures, fix the destination and retry. Destinations may acknowledge delivered events.
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
correlationIdper 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
- Register the device or system in the console (or discover it via
GET /api/v1/devices). - Create an API key for the edge agent and store it securely.
- Confirm an active flow accepts your message type and source.
- Send a test event with a unique
correlationId; expect202 Acceptedwithrouted: true. - Inspect the message detail and confirm every delivery is Delivered.
- Add heartbeat calls and monitor
metricsandalertsin staging. - Handle
401(rotate key),404(re-register device) and409(ack before delivered) explicitly in the agent.
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.