# API Overview

> [!note] Deze pagina is nog niet in het Nederlands beschikbaar en wordt in het Engels weergegeven.


The Elements Hub REST API provides comprehensive access to device discovery, connection, measurement acquisition, calibration, image streaming, and self-administration. This page is the top-level map — every section links to the detailed reference for the matching endpoints.

For an interactive way to explore and try the API see the [Swagger UI Guide](rhopoint-elements-hub-swagger-ui-guide.md). For strongly typed client libraries see [Client Code Generation](rhopoint-elements-hub-client-code-generation.md).

### API Version

Current version: **1.0**

All endpoints are versioned and follow the pattern: `/v1/{resource}`. The default base URL is `http://localhost:42042` — see [Network Binding](rhopoint-elements-hub-security-notice.md#network-binding) for how to change it.

### Workflow at a Glance

Almost every integration follows the same sequence. See [Endpoints — Functionality](rhopoint-elements-hub-endpoints-functionality.md) for the prose walkthrough and step-by-step links:

1. [Initialize lifecycle services](rhopoint-elements-hub-endpoints-functionality-lifecycle.md)
2. [Start a device scan](rhopoint-elements-hub-endpoints-functionality-device-scans.md)
3. [Connect to a discovered device](rhopoint-elements-hub-endpoints-functionality-connected-devices.md)
4. [Calibrate](rhopoint-elements-hub-endpoints-functionality-calibrations.md) (where required)
5. [Trigger measurements](rhopoint-elements-hub-endpoints-functionality-measurement-triggers.md) and / or [consume image streams](rhopoint-elements-hub-endpoints-functionality-image-streams.md)
6. [Disconnect](rhopoint-elements-hub-endpoints-functionality-connected-devices.md#disconnecting-a-device)
7. [Shut down lifecycle services](rhopoint-elements-hub-endpoints-functionality-lifecycle.md)

### Endpoint Reference

| Area | Reference | Endpoints |
| --- | --- | --- |
| Service lifecycle | [Lifecycle](rhopoint-elements-hub-endpoints-functionality-lifecycle.md) | `POST /v1/lifecycle/initialize`, `POST /v1/lifecycle/shutdown` |
| Device discovery | [Device Scans](rhopoint-elements-hub-endpoints-functionality-device-scans.md) | `POST/GET/DELETE /v1/device-scans`, `GET /v1/available-devices` |
| Device connection | [Connected Devices](rhopoint-elements-hub-endpoints-functionality-connected-devices.md) | `POST/GET/DELETE /v1/devices`, property lookup |
| Measurements | [Measurement Triggers](rhopoint-elements-hub-endpoints-functionality-measurement-triggers.md) | `GET/POST /v1/devices/{deviceId}/measurement-triggers`, `POST /v1/measurements/decode` |
| Calibration | [Calibrations](rhopoint-elements-hub-endpoints-functionality-calibrations.md) | `GET/POST /v1/devices/{deviceId}/calibrations`, `GET /calibrations/status` |
| Live imaging | [Image Streams](rhopoint-elements-hub-endpoints-functionality-image-streams.md) | `POST/DELETE /v1/devices/{deviceId}/image-streams/{sourceKey}`, `start`/`configure`/`snapshot`/`stream` |
| Host diagnostics | [System](rhopoint-elements-hub-endpoints-functionality-system.md) | `GET /v1/system/version`, `GET /v1/system/checks`, `POST /v1/system/errors/raise-exception` |
| Self-update | [App Updates](rhopoint-elements-hub-endpoints-functionality-app-updates.md) | `GET /v1/app-updates/info`, `POST /v1/app-updates/action` |

### Cross-Cutting Topics

- [Error Handling](rhopoint-elements-hub-error-handling.md) — uniform `ErrorInfo` response format and the `id.rhopointservice.com/E<n>` reference URLs.
- [Security Notice](rhopoint-elements-hub-security-notice.md) — current authentication and transport posture; **important to read before exposing the hub on a network**.
- [Measurement Image Formats](rhopoint-elements-hub-measurement-image-formats.md) — encoding of device images inside measurement containers (PNG / JPEG / raw).
- [RAE File Format](rhopoint-elements-hub-rae-file-format.md) — binary layout of the measurement container produced by `Measurement Triggers`.
- [Mock Devices](rhopoint-elements-hub-mock-devices.md) — running the API without physical hardware for development and CI.

### Core Concepts

#### Devices

- **Available Devices** — devices discovered by a running scan that can be connected. See [Polling Discovered Devices](rhopoint-elements-hub-endpoints-functionality-device-scans.md#polling-discovered-devices).
- **Connected Devices** — devices currently connected and ready for operations. See [Connected Devices](rhopoint-elements-hub-endpoints-functionality-connected-devices.md).
- **Device Class** — identifies the model behind a device record (e.g. `aesthetix`, `aesthetix-inline`, `id-inline`, plus `-mock` variants). The class drives which calibrations, measurements and image sources are available — see [Aesthetix](rhopoint-elements-hub-instruments-aesthetix.md) for one example.

#### Scans

- **Device Scans** — background processes that discover available devices on the network or attached via USB. See [Device Scans](rhopoint-elements-hub-endpoints-functionality-device-scans.md).
- One scan covers exactly one device class. To search for multiple classes in parallel, start multiple scans.

#### Measurements & Operations

- **Measurement Triggers** — commands that initiate data acquisition from connected devices. See [Measurement Triggers](rhopoint-elements-hub-endpoints-functionality-measurement-triggers.md).
- **Calibrations** — operations that re-reference the device's measurement chain against known standards. See [Calibrations](rhopoint-elements-hub-endpoints-functionality-calibrations.md).
- **Commands** — device-class–specific actions, discoverable via `GET /v1/devices/{deviceId}/commands`.
- **Container Formats** — output containers for measurements, currently `raeBinary` (default) and `raeJson`. See [Container Formats](rhopoint-elements-hub-endpoints-functionality-measurement-triggers.md#container-formats) and [RAE File Format](rhopoint-elements-hub-rae-file-format.md).

### HTTP Methods Used

| Method | Usage |
| --- | --- |
| `GET` | Retrieve information (devices, scans, status, snapshots). |
| `POST` | Create resources or initiate operations (connect devices, start scans, trigger measurements, run calibrations). |
| `DELETE` | Remove resources (disconnect devices, stop scans, stop image streams). |

### Content Types

#### Request

- `application/json` — used by every endpoint that accepts a body, except `POST /v1/measurements/decode`.
- `multipart/form-data` — only by `POST /v1/measurements/decode` (file upload for RAE decoding, see [Decoding the Container Client-Side](rhopoint-elements-hub-endpoints-functionality-measurement-triggers.md#decoding-the-container-client-side)).

#### Response

| Content type | Endpoint(s) |
| --- | --- |
| `application/json` | Standard API responses, including `ErrorInfo` payloads — see [Error Handling](rhopoint-elements-hub-error-handling.md). |
| `application/vnd.rhopoint.rae+binary` | `POST /v1/devices/{deviceId}/measurement-triggers` with `containerFormat: raeBinary` — see [RAE File Format](rhopoint-elements-hub-rae-file-format.md). |
| `image/png` / `image/jpeg` / `image/bmp` | Snapshots and single-image endpoints — see [Snapshot — Single Frame](rhopoint-elements-hub-endpoints-functionality-image-streams.md#snapshot-single-frame). |
| `image/x-raw` | Raw device images embedded in a measurement container — see [Measurement Image Formats](rhopoint-elements-hub-measurement-image-formats.md). |
| `text/event-stream` | Live image streams — see [Consuming the Stream (SSE)](rhopoint-elements-hub-endpoints-functionality-image-streams.md#consuming-the-stream-sse). |
| `text/plain` | `GET /v1/logs`. |

### Response Patterns

Successful responses use the shape documented on each endpoint's reference page. There is no uniform "envelope" wrapping every response — for example, `GET /v1/devices` returns a JSON array of device records, `GET /v1/system/version` returns an object, and a successful measurement returns the raw RAE container as a binary body.

Error responses always follow a single schema, regardless of which endpoint produced them. See [Error Handling](rhopoint-elements-hub-error-handling.md) for the full `ErrorInfo` format, the `errorCode`/`errorUrl` contract, and recommended client patterns.

### Authentication

None. Any caller that can reach the listening socket can call every endpoint. Read [Security Notice](rhopoint-elements-hub-security-notice.md) before binding the hub to anything other than `localhost`.

### Rate Limiting

Currently, no rate limiting is implemented, but clients should:

- Avoid excessive polling of [`GET /v1/available-devices`](rhopoint-elements-hub-endpoints-functionality-device-scans.md) or status endpoints — once a second is typically sufficient.
- Allow adequate time between measurement triggers — many measurements take several seconds on the device side.
- Reuse a single connection over many measurements rather than connect/disconnect cycles; see [Connected Devices — Best Practices](rhopoint-elements-hub-endpoints-functionality-connected-devices.md#best-practices).

### Asynchronous Operations

A few operations follow a start-then-poll pattern rather than blocking on the response:

- [Device scanning](rhopoint-elements-hub-endpoints-functionality-device-scans.md) — `POST` starts the scan, `GET /v1/available-devices` polls for results, `DELETE` stops.
- [Application download](rhopoint-elements-hub-endpoints-functionality-app-updates.md) — `POST .../action "download"` stages the update, `GET .../info` reports `updateDownloaded`.
- [Image streams](rhopoint-elements-hub-endpoints-functionality-image-streams.md) — `POST .../start` enables the stream, `GET .../stream` opens an SSE subscription, `DELETE` tears down.

Connect / disconnect, measurements and calibrations are **synchronous**: the `POST` does not return until the operation has finished on the device. Make sure the HTTP client timeout is long enough — at least 30 s is a safe baseline for measurements and calibrations.