---
title: Start a rule proposal
description: Start generating a proposed Cloud SIEM detection rule from a natural-language description, or from an SPL or KQL rule.
breadcrumbs: Docs > API > Start a rule proposal
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Start a rule proposal

## v2 (latest)

{% alert level="warning" %}
**Note**: This endpoint is in Preview and is subject to change.
To request access, contact [Datadog support](https://docs.datadoghq.com/help.md) or your Customer Success Manager.
{% /alert %}

| Datadog site      | API endpoint                                                                  |
| ----------------- | ----------------------------------------------------------------------------- |
| app.datadoghq.com | POST https://api.datadoghq.com/api/v2/security_monitoring/rules/proposals     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/security_monitoring/rules/proposals |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/security_monitoring/rules/proposals |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v2/security_monitoring/rules/proposals      |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/security_monitoring/rules/proposals |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/security_monitoring/rules/proposals |
| uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/security_monitoring/rules/proposals |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v2/security_monitoring/rules/proposals      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v2/security_monitoring/rules/proposals  |

### Overview

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.

This endpoint requires the `security_monitoring_rules_write` permission.

OAuth apps require the `security_monitoring_rules_write` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#security-monitoring) to access this endpoint.

### Request

#### Body Data (required)

{% tabs %}
{% tab label="Model" %}
| Parent field | Field                   | Type   | Description                                                                                                                                                                                                                                                                                                                                              |
| ------------ | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|              | data [*required*]       | object | Data of the rule proposal to start.                                                                                                                                                                                                                                                                                                                      |
| data         | attributes [*required*] | object | Attributes of the rule proposal to start.                                                                                                                                                                                                                                                                                                                |
| attributes   | input [*required*]      | string | The natural-language description or rule to generate the proposed rule from, in the format given by `inputType`.                                                                                                                                                                                                                                         |
| attributes   | inputType [*required*]  | enum   | 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. Allowed enum values: `natural_language`, `spl`, `kql`. |
| data         | type [*required*]       | enum   | The rule proposal resource type. The value is always `rule_proposals`. Allowed enum values: `rule_proposals`. Default: `rule_proposals`.                                                                                                                                                                                                                 |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "type": "rule_proposals",
    "attributes": {
      "inputType": "natural_language",
      "input": "Detect repeated failed Okta logins followed by a successful login from the same IP."
    }
  }
}
```
{% /tab %}
{% /tabs %}

### Response

{% tabs %}
{% tab label="202" %}
Accepted

{% tabs %}
{% tab label="Model" %}
Response to a started rule proposal.

| Parent field | Field                   | Type   | Description                                                                                                                                             |
| ------------ | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|              | data [*required*]       | object | Data of the started rule proposal.                                                                                                                      |
| data         | attributes [*required*] | object | Attributes of the started rule proposal.                                                                                                                |
| attributes   | status [*required*]     | string | The status of the rule proposal, one of `pending`, `in_progress`, `completed`, or `failed`. For a newly started rule proposal, the status is `pending`. |
| data         | id [*required*]         | uuid   | The ID of the rule proposal. Use it as `proposal_id` to check the proposal status and get the proposed rule.                                            |
| data         | type [*required*]       | enum   | The rule proposal resource type. The value is always `rule_proposals`. Allowed enum values: `rule_proposals`. Default: `rule_proposals`.                |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "attributes": {
      "status": "pending"
    },
    "id": "c968cf83-56c2-4d54-a993-6c86dfb83527",
    "type": "rule_proposals"
  }
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="400" %}
Bad Request

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="401" %}
Unauthorized

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="403" %}
Forbidden

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="429" %}
Too many requests

{% tabs %}
{% tab label="Model" %}
API error response.

| Field               | Type     | Description       |
| ------------------- | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}
{% /tabs %}

### Code Example

{% tabs %}
{% tab label="Curl" %}
```bash
# Set your Datadog site and credentials
export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/security_monitoring/rules/proposals" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "type": "rule_proposals",
    "attributes": {
      "inputType": "natural_language",
      "input": "Detect repeated failed Okta logins followed by a successful login from the same IP."
    }
  }
}
EOF
```
{% /tab %}
{% /tabs %}
