---
title: "Add a new custom rule"
method: POST
path: "/1.1/protection/custom-rules"
tags: ["Custom rules"]
---

# Add a new custom rule

`POST /1.1/protection/custom-rules`

## Request body

- AddCustomRuleRequest
  - `data` AddCustomRuleRequestData
    - `rule_name` string, required
    - `query` string, required
    - `rule_response` 'allow' | 'captcha' | 'block' | 'device_check' | 'intent_based' | 'monetize', required — The action applied to matching requests. 'device_check' triggers a device verification challenge. 'intent_based' applies an intent-based evaluation and authorizes legitimate traffic while blocking fraud attempts. 'monetize' triggers a monetization flow leveraging an existing monetization partner. 'intent_based' and 'monetize' values are ONLY valid when overridden_bot references an AI Agent. Policy options (rate limit, time box) are ONLY available for 'allow' and 'intent_based'.
    - `rule_priority` 'low' | 'normal' | 'high'
    - `endpoint_type` '' | 'web' | 'account-creation' | 'login' | 'cart' | 'forms' | 'payment-web' | 'rss' | 'submit' | 'api-app-mobile' | 'account-creation-app-mobile' | 'api-app-mobile-login' | 'cart-app-mobile' | 'forms-app-mobile' | 'payment-app-mobile' | 'agentic-general' | 'agentic-account-creation' | 'agentic-login' | 'agentic-cart' | 'agentic-forms' | 'agentic-payment' | 'api' — If no endpoint type is specified, the custom rule will be applied to all endpoint types.
    - `rule_enabled` boolean — Enables or disables the rule. This property takes precedence over activated_at and expired_at and will ignore these.
    - `activated_at` string — DateTime (Format Y-m-d H:i:s UTC+0) that define the date where the rule will be activate
    - `expired_at` string — DateTime (Format Y-m-d H:i:s UTC+0) that define the date where the rule will be deactivate
    - `overridden_bot` string — UUID of the Verified Bot or AI Agent this rule applies to. When set, rate-limit policy applies_to is restricted to 'all_traffic'. Required (and must be an AI Agent) when rule_response is 'intent_based' or 'monetize'.
    - `policy_options` PolicyOptions — Optional rate-limit or time-box policy applying to a custom rule. Max one policy can be provided. Only available when rule_response is 'allow' or 'intent_based'.
      - `time_box` TimeBoxOption — Time box policy option. Restricts the rule to specific hours of the week, applying an alternative response outside the authorized window.
        - `authorized_hours_of_the_week` integer[], required — List of authorized hour slots during the week. Each integer represents an hour index from 0 (Monday 00:00) to 167 (Sunday 23:00), covering all 168 possible hour intervals in a week.
        - `response_outside_time_box` 'block' | 'captcha' | 'device_check', required — The action taken for requests received outside the authorized hours.
      - `rate_limit` RateLimitOption — Rate limit policy option. Triggers an alternative response once a request threshold is exceeded within a time window. When the rule has an overridden_bot set, applies_to MUST be 'all_traffic'; using 'ip' or 'session' in that context will return a 400 error.
        - `applies_to` 'all_traffic' | 'ip' | 'session', required — Scope over which the rate is counted. Exactly one value must be chosen. 'ip' and 'session' are NOT allowed when the custom rule has an overridden_bot set — use 'all_traffic' in that case.
        - `threshold` integer, required — Maximum number of requests allowed within the defined time frame.
        - `time_frame` '1m' | '15m' | '1h' | '4h' | '1d', required — The time window over which the threshold is evaluated.
        - `response_after_threshold` 'block' | 'captcha' | 'device_check', required — The action taken once the threshold is exceeded.

## Response `200`

Acknowledges the creation of the custom rule

## Other responses

- `400` — Lists the errors detected inside the request
- `500` — Internal Server Error

---

[API](https://skmtc.net/datadome/apis/protection-api.md) · [All operations](https://skmtc.net/datadome/apis/protection-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadome/protection-api/revisions/2576052958eb/schema)