# 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.