# API Overview

> [!note] 이 페이지는 아직 한국어로 번역되지 않아 영어로 표시됩니다.


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.