---
title: "Create"
method: POST
path: "/api/v1/alerts/rules"
tags: ["ALERTS_V1"]
---

# Create

`POST /api/v1/alerts/rules`

Create a new alert or report rule.

## Request body

- RuleCreateRequest — Create request — field-level validation happens in validate_rule_create() so we get contextual error codes instead of generic Pydantic 422s.
  - `name` string, nullable
  - `description` string, nullable
  - `rule_type` string, nullable
  - `source` string, nullable
  - `platform` string, nullable
  - `entity_type` string, nullable
  - `metric_config` MetricConfig — Typed representation of the metric_config JSON stored in alert rules.
    - `metric_name` string, required — Metric identifier, e.g. 'warehouse_daily_cost'
    - `params` MetricParams — Evaluation parameters within a metric config.
      - `comparison_type` string — 'absolute_value' or 'relative_value'
      - `threshold_type` string — 'exceeds', 'below', 'changes_by', or 'changes_by_percent'
      - `threshold_value` number — Threshold to compare against
      - `aggregation` string — 'sum', 'mean', 'max', or 'min'
      - `date_range` string — 'previous_day', 'previous_week', 'previous_month', or 'previous_year'
      - `is_percentage` boolean, nullable — Derived from threshold_type; included by templates
    - `filters` MetricFilter[]
      - `key` string, required — Filter dimension name, e.g. 'warehouse'
      - `value` string[] — Filter values, e.g. ['WH1', 'WH2'], ['all'], or ['ANY']
      - `order` integer — Display order of this filter
    - `category` string, nullable — Entity type echo; included by templates
    - `team_id` integer, nullable — RBAC team (user_group) whose resources this rule is scoped to. Stamped from the x-user-group-id header at create/update; used at fire time to scope evaluation. None = unscoped.
  - `session_id` string, nullable
  - `content_scope` string, nullable
  - `delivery` DeliveryConfig — When and where to deliver alert/report (schedule + notifiers).
    - `schedule` DeliverySchedule — When to run the alert/report.
      - `cron` string — Cron expression, e.g. '0 14 * * *'
      - `timezone` string — Timezone for the schedule
    - `notifiers` NotifierConfig[] — Where to send (email, Slack, etc.).
      - `type` string, required — 'email', 'slack', or 'webhook'
      - `recipients` string[], nullable — Email addresses; used when type is 'email'
      - `channel` string, nullable — Slack notification ID; used when type is 'slack'
      - `webhook_url` string, nullable — HTTP(S) URL for POST delivery; used when type is 'webhook'
  - `alert_message` string, nullable

## Response `201`

Successful Response

- RuleResponse
  - `id` integer, required
  - `name` string, required
  - `description` string, nullable
  - `rule_type` string, required
  - `source` string
  - `platform` string, nullable
  - `category` string, nullable
  - `entity_type` string, nullable
  - `metric_config` MetricConfig — Typed representation of the metric_config JSON stored in alert rules.
    - `metric_name` string, required — Metric identifier, e.g. 'warehouse_daily_cost'
    - `params` MetricParams — Evaluation parameters within a metric config.
      - `comparison_type` string — 'absolute_value' or 'relative_value'
      - `threshold_type` string — 'exceeds', 'below', 'changes_by', or 'changes_by_percent'
      - `threshold_value` number — Threshold to compare against
      - `aggregation` string — 'sum', 'mean', 'max', or 'min'
      - `date_range` string — 'previous_day', 'previous_week', 'previous_month', or 'previous_year'
      - `is_percentage` boolean, nullable — Derived from threshold_type; included by templates
    - `filters` MetricFilter[]
      - `key` string, required — Filter dimension name, e.g. 'warehouse'
      - `value` string[] — Filter values, e.g. ['WH1', 'WH2'], ['all'], or ['ANY']
      - `order` integer — Display order of this filter
    - `category` string, nullable — Entity type echo; included by templates
    - `team_id` integer, nullable — RBAC team (user_group) whose resources this rule is scoped to. Stamped from the x-user-group-id header at create/update; used at fire time to scope evaluation. None = unscoped.
  - `session_id` string, nullable
  - `content_scope` string, nullable
  - `delivery` object, nullable
  - `alert_message` string, nullable
  - `status` string, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `created_by` integer, required
  - `last_run` RunResponse
    - `id` integer, required
    - `rule_id` integer, required
    - `status` string, required
    - `result` object, nullable
    - `error` object, nullable
    - `message` string, nullable
    - `executed_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `destinations` object, nullable, required — Recipients this run was delivered to, snapshotted at run time (lifted from ``result.destinations``) so the run-history "Destination" column doesn't have to reach into the result blob. Computed (not an input field) so it's never read off the ORM row, which has no such column. Playground reports write ``{"emails": [...], "slack_webhook_id": ...}``; metric rules leave it unset (None).
  - `recent_runs` RecentRunResponse[]
    - `id` integer, required
    - `status` string, required
    - `executed_at` string, date-time, nullable
    - `message` string, nullable
  - `summary` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/myaltimate/apis/fastapi.md) · [All operations](https://skmtc.net/myaltimate/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/myaltimate/fastapi/revisions/6aa0788aa5dc/schema)