---
title: Ban/Unban API
updatedAt: 2026-04-02T15:35:33.000Z
---

Fetch the complete documentation index at: https://docs.watchers.io/llms.txt

# Ban/Unban API

You can ban / unban users via API

Endpoint `https://chatbackend.watchers.io/external/ban`

> ⚠️ **Regional endpoints:** Replace `chatbackend.watchers.io` with the endpoint matching your project region. See [Supported Regions](https://docs.watchers.io/docs/supported-regions) for details.
> | Region | Endpoint |
> | :--- | :--- |
> | Europe (default) | `chatbackend.watchers.io` |
> | North America | `chatbackend.us.watchers.io` |
> | South America | `chatbackend.sa.watchers.io` |
> | Asia | `chatbackend.hk.watchers.io` |
> | Africa | `chatbackend.za.watchers.io` |

**Request payload**

| Parameter                                                    | **Type**    | **Required** | **Description**                                                                                                               |
| ------------------------------------------------------------ | ----------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `roomId`                                                     | string      | Optional     | If you want ban user in the room, please ptovide the `roomid`                                                                 |
| or you can use empty `roomId` for `IN_APP` bans.             |             |              |                                                                                                                               |
| `userId`                                                     | string      | Yes          | Id of user you want to ban.                                                                                                   |
| With enabled encryption, you should use unencrypted user id. |             |              |                                                                                                                               |
| `value`                                                      | boolean     | Yes          | should be `true` if you want to ban user or `false` to unban                                                                  |
| `expires`                                                    | **string**  | Optional     | fortmat: `2024-12-31 05:33:32`                                                                                                |
| `reason`                                                     | Number ENUM | Optional     | `0 - INSULTS 1 - PERSONAL 2 -FLOOD 3 -LINKS 4 - VIOLENCE 5 - FRAUD 6 - NICKNAME 7 - POLITICAL 8 - REPEATED null -  no reason` |
| `description`                                                | **string**  | Optional     | Any text description                                                                                                          |
| `type`                                                       | ENUM        | Yes          | `IN_APP` or `IN_ROOM`                                                                                                         |

CURL examples

Ban user

```bash
curl -X 'POST' \
  'https://chatbackend.watchers.io/external/ban' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer {Bearer token from admin panel}' \
  -d '{
  "userId": "123",
  "value": true,
  "expires": "2024-12-31 05:33:32",
  "reason": 2,
  "description": "Some text",
  "type": "IN_APP"
}'
```

Unban user

```bash
curl -X 'POST' \
  'https://chatbackend.watchers.io/external/ban' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {Api key of project from admin panel}' \
  -H 'Authorization: Bearer Bearer {Bearer token from admin panel}' \
  -d '{
  "userId": "123",
  "value": false,
  "type": "IN_APP"
}'
```