System

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

Version

GET /v1/system/version

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

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

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

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

GET /v1/system/checks

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

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

{
  "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

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

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

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` responses. The endpoint deliberately fails with the chosen error category.

Use this in integration tests to ensure your client switches on errorCode and surfaces the message correctly. See Error Handling for the full response format.

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.