> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canaryedge.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Native Detection

> Full anomaly detection with regime classification, energy scores, and optional embeddings

The native Canary detection endpoint extends the Azure-compatible response with regime classification, raw energy scores, and z-scores. When a `machine_id` with an active baseline is provided, regimes are classified relative to the baseline. Without a baseline, z-scores are computed from the series itself and regimes are set to `UNKNOWN`.

## Regime Types

| Regime       | Meaning                                     |
| ------------ | ------------------------------------------- |
| `HEALTHY`    | Operating within baseline parameters        |
| `ACTIVE`     | Elevated activity but within expected range |
| `TRANSITION` | Shifting between operational states         |
| `SHOCK`      | Sudden extreme deviation from baseline      |
| `UNKNOWN`    | No baseline available for comparison        |

<ParamField body="series" type="array" required>
  Array of data points, each with `timestamp` (ISO 8601) and `value` (number). Minimum 12 points, maximum 8640 points. Timestamps must be sorted ascending with no duplicates.
</ParamField>

<ParamField body="granularity" type="string" default="none">
  Time interval between points. One of: `yearly`, `monthly`, `weekly`, `daily`, `hourly`, `minutely`, `secondly`, `microsecond`, `none`.
</ParamField>

<ParamField body="sensitivity" type="integer" default={95}>
  Detection sensitivity (0-99). Higher values flag more anomalies.
</ParamField>

<ParamField body="maxAnomalyRatio" type="number" default={0.25}>
  Maximum fraction of points that can be flagged. Must be between 0 and 0.5 (exclusive).
</ParamField>

<ParamField body="machine_id" type="string">
  Machine identifier for baseline comparison. If a baseline exists for this machine, regimes are classified using the baseline's mean and standard deviation.
</ParamField>

<ParamField body="include_energy" type="boolean" default={true}>
  Include raw energy scores in the response.
</ParamField>

<ParamField body="include_embeddings" type="boolean" default={false}>
  Include 192-dimensional embedding vectors per point.
</ParamField>

<ResponseField name="period" type="integer">
  Detected seasonality period (0 if none detected).
</ResponseField>

<ResponseField name="expectedValues" type="number[]">
  The model's expected value for each point.
</ResponseField>

<ResponseField name="upperMargins" type="number[]">
  Upper bound margin for each point.
</ResponseField>

<ResponseField name="lowerMargins" type="number[]">
  Lower bound margin for each point.
</ResponseField>

<ResponseField name="isAnomaly" type="boolean[]">
  Whether each point is an anomaly.
</ResponseField>

<ResponseField name="isNegativeAnomaly" type="boolean[]">
  Whether each point is a negative anomaly.
</ResponseField>

<ResponseField name="isPositiveAnomaly" type="boolean[]">
  Whether each point is a positive anomaly.
</ResponseField>

<ResponseField name="severity" type="number[]">
  Severity score from 0.0 to 1.0 for each point.
</ResponseField>

<ResponseField name="regimes" type="string[]">
  Per-point regime classification: `HEALTHY`, `ACTIVE`, `TRANSITION`, `SHOCK`, or `UNKNOWN`.
</ResponseField>

<ResponseField name="energies" type="number[]">
  Raw prediction error (energy) per point.
</ResponseField>

<ResponseField name="z_scores" type="number[]">
  Normalized energy relative to baseline (or series mean if no baseline).
</ResponseField>

<ResponseField name="embeddings" type="number[][]">
  192-dimensional embedding vectors per point (null unless `include_embeddings` is true).
</ResponseField>

<ResponseField name="model_version" type="string">
  Model checkpoint version identifier.
</ResponseField>

<ResponseField name="engine" type="string">
  Engine identifier (e.g., `canary-v1`).
</ResponseField>

<ResponseField name="inference_time_ms" type="number">
  Inference wall time in milliseconds.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.canaryedge.com/v1/detect \
    -H "Content-Type: application/json" \
    -H "X-Canary-Key: YOUR_API_KEY" \
    -d '{
      "series": [
        {"timestamp": "2024-01-01T00:00:00Z", "value": 1.0},
        {"timestamp": "2024-01-01T00:01:00Z", "value": 1.1},
        {"timestamp": "2024-01-01T00:02:00Z", "value": 0.9},
        {"timestamp": "2024-01-01T00:03:00Z", "value": 1.0},
        {"timestamp": "2024-01-01T00:04:00Z", "value": 1.2},
        {"timestamp": "2024-01-01T00:05:00Z", "value": 0.8},
        {"timestamp": "2024-01-01T00:06:00Z", "value": 1.1},
        {"timestamp": "2024-01-01T00:07:00Z", "value": 1.0},
        {"timestamp": "2024-01-01T00:08:00Z", "value": 0.9},
        {"timestamp": "2024-01-01T00:09:00Z", "value": 1.0},
        {"timestamp": "2024-01-01T00:10:00Z", "value": 5.0},
        {"timestamp": "2024-01-01T00:11:00Z", "value": 1.0}
      ],
      "granularity": "minutely",
      "sensitivity": 95,
      "machine_id": "pump-47",
      "include_energy": true,
      "include_embeddings": false
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "period": 0,
    "expectedValues": [1.0, 1.05, 0.95, 1.0, 1.1, 0.9, 1.05, 1.0, 0.95, 1.0, 3.0, 1.5],
    "upperMargins": [0.12, 0.13, 0.11, 0.12, 0.14, 0.10, 0.13, 0.12, 0.11, 0.12, 2.5, 0.15],
    "lowerMargins": [0.12, 0.13, 0.11, 0.12, 0.14, 0.10, 0.13, 0.12, 0.11, 0.12, 2.5, 0.15],
    "isAnomaly": [false, false, false, false, false, false, false, false, false, false, true, false],
    "isNegativeAnomaly": [false, false, false, false, false, false, false, false, false, false, false, false],
    "isPositiveAnomaly": [false, false, false, false, false, false, false, false, false, false, true, false],
    "severity": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.85, 0.0],
    "regimes": ["HEALTHY", "HEALTHY", "HEALTHY", "HEALTHY", "HEALTHY", "HEALTHY", "HEALTHY", "HEALTHY", "HEALTHY", "HEALTHY", "SHOCK", "HEALTHY"],
    "energies": [0.02, 0.03, 0.02, 0.02, 0.03, 0.02, 0.03, 0.02, 0.02, 0.02, 4.5, 0.03],
    "z_scores": [0.1, 0.3, 0.1, 0.1, 0.3, 0.1, 0.3, 0.1, 0.1, 0.1, 12.5, 0.3],
    "embeddings": null,
    "model_version": "canary-v0.1",
    "engine": "canary-v1",
    "inference_time_ms": 2.3
  }
  ```
</ResponseExample>