---
title: "Create Org Alert Policy Rule"
method: POST
path: "/orgs/{org_slug}/alert-policies/{policy_id}/rules"
tags: ["alert-policies"]
---

# Create Org Alert Policy Rule

`POST /orgs/{org_slug}/alert-policies/{policy_id}/rules`

## Request

- Base URL: `https://api.socket.dev/v0`
- URL: `https://api.socket.dev/v0/orgs/{org_slug}/alert-policies/{policy_id}/rules`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

Create a rule on an alert policy. Rules are evaluated in ascending rank order and the first matching rule decides the alert action. Provide at most one of `position`, `rank`, `before_rule_id`, or `after_rule_id`; the rule is placed first when no position is provided. Requires a token with org-wide repository access; repo-restricted tokens receive 403.

This endpoint consumes 1 unit of your quota.

This endpoint requires the following org token scopes:
- alert-policy:create

## Path parameters

- `org_slug` string, required
- `policy_id` string, required

## Query parameters

- `dry_run` boolean

## Request body

- object
  - `name` string, required: The rule name (1-128 characters).
  - `vigil_selector` object, required: Selector describing which alerts the rule applies to. Fields must all be under finding.*, location.*, or artifact.* (e.g. `{"finding.alertType": "criticalCVE", "artifact.name": "lodash"}`).
  - `action` string, required: The action applied to matching alerts. One of: error, warn, monitor, ignore.
  - `note` string, nullable: Operator-provided note (up to 256 characters).
  - `position` string: Where to place the rule within the policy: `first` or `last`. Mutually exclusive with `rank`, `before_rule_id`, and `after_rule_id`; when no position is provided a created rule is placed first.
  - `rank` string: Explicit rank, as a `fractional-indexing` base62 order key (e.g. `a0`, `a0V`). Prefer `position`, `before_rule_id`, or `after_rule_id`; a rank that is not a valid order key is rejected.
  - `before_rule_id` string, nullable: Place the rule immediately before this rule UUID.
  - `after_rule_id` string, nullable: Place the rule immediately after this rule UUID.

## Response `200`

Dry-run: the write was not persisted.

- object
  - `id` string, required: The UUID of the rule.
  - `alert_policy_id` string, required: The UUID of the policy the rule belongs to.
  - `rank` string, required: Fractional-index rank; rules are evaluated in ascending rank order.
  - `name` string, required: The rule name.
  - `vigil_selector` object, required: Selector describing which alerts the rule applies to. Fields must all be under finding.*, location.*, or artifact.* (e.g. `{"finding.alertType": "criticalCVE", "artifact.name": "lodash"}`).
  - `action` 'error' | 'warn' | 'monitor' | 'ignore', required: The action applied to matching alerts. One of: error, warn, monitor, ignore.
  - `note` string, nullable, required: Operator-provided note.
  - `created_by` string, nullable, required: User ID that created the rule.
  - `updated_by` string, nullable, required: User ID that last updated the rule.
  - `created_at` string, required: ISO-8601 creation timestamp.
  - `updated_at` string, required: ISO-8601 last-update timestamp.
  - `dry_run` boolean: True when `?dry_run=true` (or `1` / `yes`) rehearsed the write; nothing was persisted.

## Other responses

- `201`: The created alert policy rule.
- `400`: Bad request
- `401`: Unauthorized
- `403`: Insufficient max_quota for API method
- `404`: Resource not found
- `409`: Resource already exists
- `429`: Insufficient quota for API route

## Changes

- **2026-11-03** `5ad8bf36b1e7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/socket-dev/apis/socket/changes/orgs/:org_slug/alert-policies/:policy_id/rules/post.md)

---

[API](https://skmtc.dev/socket-dev/apis/socket.md) - [All operations](https://skmtc.dev/socket-dev/apis/socket/llms.txt) - [OpenAPI document](https://skmtc.dev/socket-dev/apis/socket/revisions/5ad8bf36b1e7?raw)