---
title: "Start a rule proposal"
method: POST
path: "/api/v2/security_monitoring/rules/proposals"
tags: ["Security Monitoring"]
---

# Start a rule proposal

`POST /api/v2/security_monitoring/rules/proposals`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/security_monitoring/rules/proposals`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `security_monitoring_rules_write`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/security_monitoring/rules/proposals/post.ts> (a function with typed inputs; its response is checked against the schema)

Start generating a proposed Cloud SIEM detection rule from a natural-language
description, or from an SPL or KQL rule. The proposal is based on your organization's
log sources, log fields, and existing detection rules. When logs from the matching
source are available, the proposed query is tested against your recent logs.

The proposed rule is generated asynchronously. This endpoint returns a proposal `id`
with the status `pending`. To get the proposed rule, pass this `id` to the get-a-rule-proposal
endpoint and poll the endpoint until the status is `completed` or `failed`. A proposal
usually takes a few minutes, and up to 10 minutes.

This endpoint does not create or modify any detection rules in Cloud SIEM. To translate
many rules at once, use batch migrations instead.

## Request body

- SecurityMonitoringRuleProposalStartRequest: Request to start a rule proposal.
  - `data` SecurityMonitoringRuleProposalStartRequestData, required: Data of the rule proposal to start.
    - `attributes` SecurityMonitoringRuleProposalStartRequestAttributes, required: Attributes of the rule proposal to start.
      - `input` string, required: The natural-language description or rule to generate the proposed rule from, in the format given by `inputType`.
      - `inputType` 'natural_language' | 'spl' | 'kql', required: The type of input to generate the proposed rule from: `natural_language` for a plain-English description of the behavior to detect, `spl` for a Splunk SPL search or saved search definition, or `kql` for a Microsoft KQL query. SPL inputs must be self-contained, with search macros expanded.
    - `type` 'rule_proposals', required: The rule proposal resource type. The value is always `rule_proposals`.

## Response `202`

Accepted

- SecurityMonitoringRuleProposalStartResponse: Response to a started rule proposal.
  - `data` SecurityMonitoringRuleProposalStartResponseData, required: Data of the started rule proposal.
    - `attributes` SecurityMonitoringRuleProposalStartResponseAttributes, required: Attributes of the started rule proposal.
      - `status` string, required: The status of the rule proposal, one of `pending`, `in_progress`, `completed`, or `failed`. For a newly started rule proposal, the status is `pending`.
    - `id` string, uuid, required: The ID of the rule proposal. Use it as `proposal_id` to check the proposal status and get the proposed rule.
    - `type` 'rule_proposals', required: The rule proposal resource type. The value is always `rule_proposals`.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)