Calibrations

Calibration brings a connected device's measurement chain back into agreement with a known reference (white, black, or height target). For instruments such as Aesthetix, a valid calibration is a precondition for trustworthy measurements — running a measurement on an uncalibrated device returns numbers, but they are not metrologically meaningful. The hub tracks the last calibration time per device and exposes a status endpoint so clients can prompt for re-calibration before it goes stale.

Endpoints Overview

Listing Available Calibrations

GET /v1/devices/{deviceId}/calibrations

curl http://localhost:42042/v1/devices/12f1d7dd07ac42a088c8f961b39d68ff/calibrations

Returns the device's calibration definitions, including the parameters each one accepts. Example shape:

[
  {
    "identifier": "white",
    "title": "White Calibration",
    "description": "Performs white reference calibration using the white calibration standard.",
    "category": "calibration",
    "parameters": [
      { "key": "reflectance",    "type": "Double", "description": "Percent, 0.42 ≙ 42 %" },
      { "key": "visualContrast", "type": "Double", "description": "Percent, 0.42 ≙ 42 %" }
    ]
  }
]

The set of calibrations is device-class–specific. For example, an Aesthetix supports white, black and height, an Aesthetix Inline only black. See Aesthetix-specific calibration details.

Executing a Calibration

POST /v1/devices/{deviceId}/calibrations
Content-Type: application/json

{
  "calibrationKey": "white",
  "parameters": [
    { "key": "reflectance",    "value": 0.95 },
    { "key": "visualContrast", "value": 0.92 }
  ]
}

curl -X POST http://localhost:42042/v1/devices/12f1d7dd07ac42a088c8f961b39d68ff/calibrations \
  -H "Content-Type: application/json" \
  -d '{
    "calibrationKey": "white",
    "parameters": [
      { "key": "reflectance",    "value": 0.95 },
      { "key": "visualContrast", "value": 0.92 }
    ]
  }'

Request Body

Response

{
  "calibrationKey": "white",
  "success": true
}

The call is synchronous and only returns once the calibration has completed on the device. Calibration can take several seconds; clients should set a generous HTTP timeout (≥30 s).

The physical calibration target must be in place before the request is sent. Calibrating against the wrong target will produce a successful response but invalid downstream measurements. See the device-specific calibration page for which target to use with which calibrationKey.

Getting the Calibration Status

GET /v1/devices/{deviceId}/calibrations/status

Returns the current state of every calibration type the device supports:

{
  "deviceId": "12f1d7dd07ac42a088c8f961b39d68ff",
  "deviceSerialNumber": "AXI8000027",
  "calibrations": [
    {
      "calibrationKey": "white",
      "lastCalibrationTime": "2025-11-10T07:32:14.000Z",
      "status": "CalibrationValid",
      "recommendedInterval": "2.00:00:00",
      "overdueInterval": "7.00:00:00"
    },
    {
      "calibrationKey": "black",
      "lastCalibrationTime": null,
      "status": "NotCalibrated",
      "recommendedInterval": "2.00:00:00",
      "overdueInterval": "7.00:00:00"
    }
  ]
}

Status Values

The intervals follow .NET TimeSpan formatting (d.hh:mm:ss). Typical defaults are 2 days (recommended) and 7 days (overdue), but the device definition is authoritative — read the values from the response rather than hard-coding them.

Persistence

Calibration data is stored per serial number + device class, not per session identifier. Disconnecting and re-connecting a device — or restarting the hub — does not invalidate previously persisted calibrations. The storage location is the dataDirectory passed to `POST /v1/lifecycle/initialize`.

Best Practices

• After connecting a device, call GET /v1/devices/{deviceId}/calibrations/status and surface any NotCalibrated, CalibrationRecommended or CalibrationOverdue entries to the operator before allowing measurements to start.
• Calibrate in the order recommended by the device manufacturer (typically Black → White → Height for Aesthetix). Some calibrations depend on earlier ones being valid.
• Read parameters from GET /v1/devices/{deviceId}/calibrations and only send the values listed there — sending unknown keys is silently ignored, which makes typos hard to spot.
• Time the calibration prompts using the status endpoint, not your own scheduler — the intervals can change between firmware updates.

Error Cases

See Error Handling for the response format.