# System

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


The system endpoints expose diagnostic information about the running Elements Hub instance and its host machine. They are useful during deployment, support sessions, and for verifying that a client's error-handling path works end-to-end.

### Endpoints Overview

| Method | Endpoint | Description |
| --- | --- | --- |
| GET | `/v1/system/version` | Hub version and environment information |
| GET | `/v1/system/checks` | Run the built-in host system checks |
| POST | `/v1/system/errors/raise-exception` | Trigger a controlled error response (testing only) |

### Version

```http
GET /v1/system/version
```

```bash
curl http://localhost:42042/v1/system/version
```

Returns the version of the running hub and which environment it was built for:

```json
{
  "version": "1.7.0+abc1234",
  "environment": "release",
  "componentVersions": {}
}
```

| Field | Type | Description |
| --- | --- | --- |
| `version` | string | Hub version including build metadata. |
| `environment` | string | Build category (e.g. `release`, `debug`, `nightly`). |
| `componentVersions` | object | Map of internal component → version. May be empty in production builds. |

> [!note]
> If `version` returns `"###version###"` and `environment` returns `"###category###"`, you are running a build whose version placeholders were not replaced — typically a developer build straight from source. Treat this as "unversioned" rather than a real release.

### System Checks

```http
GET /v1/system/checks
```

```bash
curl http://localhost:42042/v1/system/checks
```

Runs a short series of host checks and returns the aggregated result:

```json
{
  "passed": true,
  "runs": [
    {
      "runIdentifier": 1,
      "status": "Passed",
      "details": "USB Controller Version 3"
    },
    {
      "runIdentifier": 2,
      "status": "Passed",
      "details": "Minimum Memory"
    },
    {
      "runIdentifier": 3,
      "status": "Passed",
      "details": "Free Memory"
    }
  ]
}
```

#### Checks Performed

| Check | Requirement | Severity |
| --- | --- | --- |
| **USB Controller Version 3** | At least one xHCI (USB 3.x) controller is present. | Error |
| **Minimum Memory** | The host has at least 8 GB of installed RAM. | Error |
| **Free Memory** | At least 2 GB of RAM is currently free. | Warning |

`passed` reflects the aggregate: it is `true` only if every error-severity check passed. Warning-severity checks contribute to the per-run `status` but do not flip the top-level `passed` flag.

#### When to Run the Checks

- After installation, before connecting hardware for the first time.
- When a support session starts — the output is small and pastes cleanly into a ticket.
- As an automated readiness probe in container/VM deployments.

### Triggering a Controlled Error

```http
POST /v1/system/errors/raise-exception?errorType=device
```

```bash
curl -X POST "http://localhost:42042/v1/system/errors/raise-exception?errorType=device"
```

Used to verify that a client correctly parses and reacts to [`ErrorInfo`](rhopoint-elements-hub-error-handling.md) responses. The endpoint deliberately fails with the chosen error category.

| `errorType` | Triggers |
| --- | --- |
| `device` | A device-layer exception (`ErrorInfo` with `errorCode = E31`). |
| `notfound` | An HTTP 404 (`ErrorInfo` with `errorCode = E31`). |
| `unhandled` | An uncaught exception, exercising the global exception handler. |
| anything else | HTTP 400 (`ErrorInfo` with `errorCode = E31`). |

Use this in integration tests to ensure your client switches on `errorCode` and surfaces the `message` correctly. See [Error Handling](rhopoint-elements-hub-error-handling.md) for the full response format.

> [!warning]
> This endpoint exists exclusively for testing. Do not call it from production code paths.

### Best Practices

- Cache the `version` response on the client; it does not change at runtime.
- Run `/checks` once at start-up and surface failures to the operator before allowing measurements. Use it in CI to verify that test hosts meet the minimum requirements.
- Pin client behaviour to `errorCode` values returned by the test endpoint — if you can handle `E31` correctly, the rest of the error surface tends to fall in line.