---
title: "Create Rule"
method: POST
path: "/notifications/rules"
tags: ["notification-rules"]
---

# Create Rule

`POST /notifications/rules`

## Request

- Base URL: `https://api-docs.upsmith.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.upsmith.com/notifications/rules`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Store a new rule as a draft. It is not activated, by this or by any other client.

## Headers

- `organization-id` string, nullable
- `x-user-id` string, nullable
- `timezone` string
- `x-actor-email` string, nullable
- `x-request-source` string, nullable
- `x-operation-id` string, nullable
- `x-commit-message` string, nullable
- `x-confirmation-id` string, nullable
- `x-chat-id` string, nullable

## Request body

- RuleCreateRequest: A new rule. It is a draft: creating one never starts it routing traffic. No ``base_version`` — there is no version to be stale against. The first save of a rule is the only write that does not need one.
  - `name` string, nullable
  - `event_types` string[]
  - `decision` object, required

## Response `200`

Successful Response

- RuleSaveResponse: The stored rule, and why it still cannot notify anyone. ``warnings`` non-empty means the save succeeded and activation will not: the document is well formed and structurally inert. Returning it here is what lets an author keep a draft they have not finished.
  - `now_uncovered` string[]
  - `rule` RuleResponse, required
    - `activated_by_user_id` string, nullable
    - `activated_at` string, date-time, nullable
    - `deactivated_by_user_id` string, nullable
    - `deactivated_at` string, date-time, nullable
    - `id` string, required
    - `rule_key` string, required
    - `name` string, nullable, required
    - `event_types` string[], required
    - `version` integer, required
    - `is_active` boolean, required
    - `created_by_user_id` string, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `unreachable_recipients` UnreachableRecipient[]
      - `kind` 'user' | 'entity' | 'technician' | 'rotation', required: What a recipient reference names, and in whose id space. The three destinations ``notification.recipient.type`` has, restated so a rule document needs no ORM to be authored or validated, plus a rotation, which names a schedule rather than a row; ``tests/test_outputs.py`` holds the two lists together, as it does for the escalation reasons. Which id a reference carries follows from its kind, the way every notification settings route already reads one: ``user`` carries an ``auth.user.id``, ``entity`` and ``technician`` carry a ``notification.recipient.id``, neither having a user behind it, and ``rotation`` carries a rotation id (:func:`parse_rotation_id`). So every recipient a subscription names can be written as one of the first three, and the kind says what the reference can receive rather than hiding it behind a read. A reference is resolved to a person when the message is sent, never here -- which is what lets an escalation step reach whoever is on call at that moment rather than whoever was when the event happened.
      - `id` string, required
      - `reasons` IneligibilityReason[], required
    - `explanation` RuleExplanation: One rule, in plain English, rendered from the document rather than written by a model. ``sentence`` is the whole thing and is what a client prints. ``when`` and ``then`` are the halves it is built from, for a client that lays the two out rather than printing one line. Both are the same rendering: a client that uses the parts never disagrees with one that uses the sentence. It describes the document, never an event. Whether the condition would match anything is preview's answer.
      - `sentence` string, required
      - `when` string, required
      - `then` string[]
    - `decision` object, required
  - `warnings` RuleIssue[], required
    - `path` string, required
    - `message` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/upsmith/apis/upsmith-api.md) - [All operations](https://skmtc.dev/upsmith/apis/upsmith-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upsmith/apis/upsmith-api/revisions/86e2c2bd93af?raw)