---
title: "Rule overrides API"
description: "API reference for Alpacon per-server rule overrides. Give one server its own threshold, recovery threshold, or duration, or exempt it from an alert rule."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Rule overrides

**Endpoint**: `/api/metrics/rule-overrides/`

An override is one server's departure from an [alert rule](/reference/api/metrics/rules/) it's attached to: its own threshold, recovery threshold, or duration, or an exemption from the rule entirely. It doesn't change the rule for any other server. The same settings are on the server's **Rules** tab in the console—see [Per-server overrides](/use/servers/monitor/#per-server-overrides), and [Metric alerts](/use/servers/monitor/#metric-alerts) for how overrides fit into how a rule fires.

Requires the Metrics extension to be enabled for the workspace, and only reaches servers the credential can already manage—naming any other server is answered as not found.

## Who can manage overrides

An override follows the usual [`rule_override` scopes](/reference/scopes/#rule_override) for every rule except the [core disk-usage rule](/reference/api/metrics/rules/#the-core-disk-usage-rule). On that one, only a workspace admin may create, update, or delete an override, or move an override onto or off it—an operator and every service token get 403 `metrics_alert_rule_core_admin_only`, checked before the rest of the request body.

  
    ## List rule overrides

    Retrieve a paginated list of rule overrides.

    ### Request

    ```http
    GET /api/metrics/rule-overrides/
    ```

    ### Query parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `server` | UUID | Filter by server ID |
    | `rule` | UUID | Filter by alert rule ID |
    | `enabled` | boolean | Filter by whether the override is active (`false` is the exemption) |
    | `search` | string | Search across server name and rule name |
    | `ordering` | string | Sort order (e.g., `added_at`, `-updated_at`). Default: `-added_at` |
    | `page` | integer | Page number |
    | `page_size` | integer | Results per page (default: 15, max: 100) |

    ### Response

    ```json
    {
      "count": 1,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
          "server": {
            "id": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
            "name": "web-server-01",
            "os": "Ubuntu 22.04",
            "is_connected": true
          },
          "rule": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
          "threshold": 90,
          "recovery_threshold": 80,
          "duration_s": null,
          "enabled": true,
          "added_at": "2026-09-10T09:00:00Z",
          "updated_at": "2026-09-10T09:00:00Z"
        }
      ]
    }
    ```

    Required scope: [`rule_override:read`](/reference/scopes/#rule_override-read)

    ### Example

    ```bash
    curl -X GET "https://your-workspace.us1.alpacon.io/api/metrics/rule-overrides/?server=7e3984de-49ab-4cc6-bcdf-21fbd35858b8" \
      -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
    ```
  

  
    ## Create rule override

    Give one server its own values for a rule it's attached to, or exempt it from that rule.

    ### Request

    ```http
    POST /api/metrics/rule-overrides/
    ```

    ### Request body

    ```json
    {
      "server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
      "rule": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
      "threshold": 90,
      "recovery_threshold": 80
    }
    ```

    ### Parameters

    | Field | Type | Required | Description |
    |-------|------|----------|-------------|
    | `server` | UUID | Yes | Server this override applies to. Must be a server the credential can manage |
    | `rule` | UUID | Yes | Alert rule to override |
    | `threshold` | number | No | Replaces the rule's threshold for this server. Leave empty to keep the rule's own value |
    | `recovery_threshold` | number | No | Replaces the rule's recovery threshold for this server. Must sit on the recovering side of the effective threshold, given the rule's direction. Leave empty to keep the rule's own value |
    | `duration_s` | integer | No | Replaces the rule's duration for this server, in seconds. Leave empty to keep the rule's own value; `0` means a single breaching sample fires |
    | `enabled` | boolean | No | `false` exempts this server from the rule entirely, whatever the other fields hold. Default `true` |

    A server may have at most one override per rule.

    ### Response

    ```json
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "server": {
        "id": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
        "name": "web-server-01",
        "os": "Ubuntu 22.04",
        "is_connected": true
      },
      "rule": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e",
      "threshold": 90,
      "recovery_threshold": 80,
      "duration_s": null,
      "enabled": true,
      "added_at": "2026-09-10T09:00:00Z",
      "updated_at": "2026-09-10T09:00:00Z"
    }
    ```

    Required scope: [`rule_override:create`](/reference/scopes/#rule_override-create)

    ### Example

    ```bash
    curl -X POST "https://your-workspace.us1.alpacon.io/api/metrics/rule-overrides/" \
      -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
      -H "Content-Type: application/json" \
      -d '{"server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8", "rule": "8c4d6e2a-1b3f-4a5c-8d9e-0f1a2b3c4d5e", "threshold": 90}'
    ```
  

  
    ## Get rule override

    Retrieve a specific rule override by ID.

    ### Request

    ```http
    GET /api/metrics/rule-overrides/{override_id}/
    ```

    ### Path parameters

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `override_id` | UUID | Yes | Rule override ID |

    ### Response

    Same schema as [Create rule override](#create-rule-override).

    Required scope: [`rule_override:read`](/reference/scopes/#rule_override-read)

    ### Example

    ```bash
    curl -X GET "https://your-workspace.us1.alpacon.io/api/metrics/rule-overrides/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/" \
      -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
    ```
  

  
    ## Update rule override

    Update an existing override. Supports partial updates via `PATCH`.

    ### Request

    ```http
    PATCH /api/metrics/rule-overrides/{override_id}/
    ```

    ### Path parameters

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `override_id` | UUID | Yes | Rule override ID |

    ### Request body

    ```json
    {
      "enabled": false
    }
    ```

    ### Parameters

    Same fields as [Create rule override](#create-rule-override), all optional, including `server` and `rule`—moving an override to a different server or rule is allowed. A server may still have at most one override per rule, so moving onto a `(server, rule)` pair that already has one fails.

    ### Response

    Returns the full override object with updated fields (same schema as [Get rule override](#get-rule-override)).

    Required scope: [`rule_override:update`](/reference/scopes/#rule_override-update)

    ### Example

    ```bash
    curl -X PATCH "https://your-workspace.us1.alpacon.io/api/metrics/rule-overrides/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/" \
      -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
      -H "Content-Type: application/json" \
      -d '{"enabled": false}'
    ```
  

  
    ## Delete rule override

    Remove an override. The server goes back to the rule's own values.

    ### Request

    ```http
    DELETE /api/metrics/rule-overrides/{override_id}/
    ```

    ### Path parameters

    | Parameter | Type | Required | Description |
    |-----------|------|----------|-------------|
    | `override_id` | UUID | Yes | Rule override ID |

    ### Response

    ```http
    204 No Content
    ```

    Required scope: [`rule_override:delete`](/reference/scopes/#rule_override-delete)

    ### Example

    ```bash
    curl -X DELETE "https://your-workspace.us1.alpacon.io/api/metrics/rule-overrides/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d/" \
      -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
    ```
  

## Error responses

| Status | Error code | Description |
|--------|------------|-------------|
| 400 | `metrics_alert_rule_recovery_threshold_invalid` | The effective `recovery_threshold` is not on the recovering side of the effective `threshold` |
| 400 | `INVALID_REQUEST` | A server already has an override for this rule, or `server` or `rule` doesn't resolve |
| 401 | `UNAUTHORIZED` | Invalid or missing authentication |
| 403 | `metrics_alert_rule_core_admin_only` | A create, update, or delete on an override of the core disk-usage rule, or a move onto or off it, from anyone but a workspace admin |
| 403 | `FORBIDDEN` | Insufficient permissions, or the Metrics extension isn't enabled for this workspace |
| 404 | `NOT_FOUND` | Override not found, or `server` names one this credential can't manage |

Source: https://docs.alpacax.com/reference/api/metrics/rule-overrides/