# WAF Banned Words

<a id="get-api-v1-banned-words"></a>
#### `GET /api/v1/banned-words`

*List word filter lists*

Every banned-word list with its category and words. A file under the wordlists directory that cannot be read as a list is named in `warnings` and is not applied.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_WordlistResponse__` | Successful Response |

**Response example (200):**

```json
{
  "data": [
    {
      "built_in": "...",
      "category": "...",
      "created_at": "...",
      "description": "...",
      "enabled": "...",
      "id": "...",
      "name": "...",
      "updated_at": "...",
      "word_count": "...",
      "words": "..."
    }
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/banned-words
```

---

<a id="post-api-v1-banned-words"></a>
#### `POST /api/v1/banned-words`

*Create word filter list*

Define a new banned-word list under a category (account_name / domain / email_subject).

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `category` | WordlistCategory | no | default `custom`; enum: `illegal`, `adult`, `gambling`, `phishing`, `malware`, `trademark`, `custom` |
| `description` | string | no | default ``; maxLength=500 |
| `enabled` | boolean | no | default `True` |
| `name` | string | yes | minLength=1; maxLength=100 |
| `words` | array<string> | no | — |

**Request body example:**

```json
{
  "category": "illegal",
  "description": "",
  "enabled": true,
  "name": "string",
  "words": [
    "string"
  ]
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_WordlistResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "built_in": false,
    "category": "custom",
    "created_at": "...",
    "description": "",
    "enabled": true,
    "id": "string",
    "name": "string",
    "updated_at": "...",
    "word_count": 0,
    "words": [
      "..."
    ]
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/banned-words
```

---

<a id="post-api-v1-banned-words-check"></a>
#### `POST /api/v1/banned-words/check`

*Test value against word filters*

Returns whether the given value would be blocked + which list matched.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `value` | string | yes | minLength=1; maxLength=1000 |

**Request body example:**

```json
{
  "value": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_BannedWordCheckResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "banned": false,
    "matched_word": "...",
    "matched_wordlist": "..."
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/banned-words/check
```

---

<a id="delete-api-v1-banned-words-wordlist-id"></a>
#### `DELETE /api/v1/banned-words/{wordlist_id}`

*Delete word filter list*

Removes the list. Active filters using this list are no longer enforced.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `wordlist_id` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/banned-words/{wordlist_id}
```

---

<a id="get-api-v1-banned-words-wordlist-id"></a>
#### `GET /api/v1/banned-words/{wordlist_id}`

*Get word filter list*

Detail view of a single list, including every blocked word.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `wordlist_id` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_WordlistResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "built_in": false,
    "category": "custom",
    "created_at": "...",
    "description": "",
    "enabled": true,
    "id": "string",
    "name": "string",
    "updated_at": "...",
    "word_count": 0,
    "words": [
      "..."
    ]
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/banned-words/{wordlist_id}
```

---

<a id="put-api-v1-banned-words-wordlist-id"></a>
#### `PUT /api/v1/banned-words/{wordlist_id}`

*Update word filter list*

Patch the list — replace words, change category, toggle enabled.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `wordlist_id` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `category` | WordlistCategory | no | — |
| `description` | string | no | — |
| `enabled` | boolean | no | — |
| `name` | string | no | — |
| `words` | array<string> | no | — |

**Request body example:**

```json
{
  "category": "illegal",
  "description": "string",
  "enabled": false,
  "name": "string",
  "words": [
    "string"
  ]
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_WordlistResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "built_in": false,
    "category": "custom",
    "created_at": "...",
    "description": "",
    "enabled": true,
    "id": "string",
    "name": "string",
    "updated_at": "...",
    "word_count": 0,
    "words": [
      "..."
    ]
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/banned-words/{wordlist_id}
```

---