---
title: "Create a custom Shield rule."
method: POST
path: "/v1/shield/custom"
tags: ["Shield"]
---

# Create a custom Shield rule.

`POST /v1/shield/custom`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/v1/shield/custom`
- Auth: HTTP bearer

Adds a customer-defined crawler rule matched by User-Agent substring, with
its own access policy. Requires the Pro plan or higher.

## Request body

- CustomRuleRequest: Request body for `POST /v1/shield/custom` — a customer-defined UA rule. The `CrawlerPolicy` fields (`action`, `rate_limit_per_min`) are flattened into the top level alongside `name` and `ua_pattern`.
  - `action` 'allow' | 'block' | 'rate_limit', required
  - `rate_limit_per_min` integer, nullable
  - `name` string, required
  - `ua_pattern` string, required: Case-insensitive substring matched against the User-Agent header.

## Response `200`

Custom rule created

- CustomRule: Customer-defined user-agent rule. Takes precedence over the built-in crawler database so customers can police bots we don't know about yet — or override how a known bot is matched.
  - `id` string, uuid, required
  - `name` string, required
  - `ua_pattern` string, required: Case-insensitive substring matched against the User-Agent header.
  - `policy` CrawlerPolicy, required
    - `action` 'allow' | 'block' | 'rate_limit', required
    - `rate_limit_per_min` integer, nullable
  - `created_at` string, date-time, required

## Other responses

- `400`: Invalid rule
- `401`: Missing or invalid credentials
- `403`: Requires Pro plan, the waf:write scope, or a project-scoped token
- `500`: Internal error

---

[API](https://skmtc.dev/scalix/apis/scalix-cloud-api.md) · [All operations](https://skmtc.dev/scalix/apis/scalix-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scalix/apis/scalix-cloud-api/revisions/2c04ca0a90bb?raw)