---
title: "Validate Rule"
method: POST
path: "/admin/notifications/rules/validate"
tags: ["admin", "notification-rules"]
---

# Validate Rule

`POST /admin/notifications/rules/validate`

## 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/admin/notifications/rules/validate`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Check a candidate document without storing it.

A document that does not validate is a 422 naming the path in the document that is wrong,
which is the same refusal a save gives — so an operator drafting a rule through the MCP
fails here rather than discovering it at write time. A 200 with warnings means the document
is well formed and still cannot notify anyone: savable, not activatable.

``explanation`` names no recipients: this route names no organization to resolve them against.
For the same reason it can check neither that a named on-call list exists nor that a
website-lead rule names only people that notification may reach; a save does both.

## Headers

- `organization-id` string, nullable
- `timezone` string
- `x-user-id` string, nullable
- `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

- RuleValidationRequest: A candidate document to check without storing it. ``event_types`` is optional because a client may be checking a document alone, but a client that has them should send them: an empty or unknown event type is a property of the rule rather than of the document, and this is the only place that can report it before a save.
  - `decision` object, required
  - `event_types` string[]

## Response `200`

Successful Response

- RuleValidationResponse: A document that parsed and checked out, and why it may still notify nobody. ``warnings`` non-empty means the document is savable but cannot be activated: it is well formed and inert. A document that does not validate never reaches this model — it is a 422. ``explanation`` reads the candidate back before anything stores it, which is the point at which an author can still tell that the document is not the rule they meant.
  - `valid` boolean, required
  - `warnings` RuleIssue[], required
    - `path` string, required
    - `message` string, 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[]

## 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)