> For the complete documentation index, see [llms.txt](https://sentineldocs.metatable.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sentineldocs.metatable.dev/luau-sdk/banapi-documentation.md).

# BanAPI Documentation

{% hint style="danger" %}
This documentation is relatively the same for v2.0.0 of the SentinelAPI, however to index/call a method properly in the BanAPI you must call it as `SentinelAPI.BanAPI:method(...)`, an example would be: `SentinelAPI.BanAPI:BanAsync(...)`
{% endhint %}

This document provides an in-depth overview of the `SentinelAPI` module, which serves as the backbone for managing bans, unbans, and other moderation-related features in Sentinel. The API interacts with Roblox services and Sentinel Open Cloud API endpoints to enforce moderation effectively.

***

### Module Overview **Dependencies**:

* `Config`: Configuration settings for Sentinel.
* `Types`: Type definitions used across Sentinel.
* `Enum`: Enum definitions for ban types and lengths.
* `RichBan`: Helper functions for advanced ban features.

***

### SentinelAPI Methods

#### 1. **BanAsync**

Bans a player from the experience.

**Signature**:

```lua
function BanAsync(Player: Player, BanConfig: types.BanConfig): boolean
```

**Parameters**:

* `Player`: The `Player` instance to ban.
* `BanConfig`: A table with configuration details (see `BanConfig` type).

**Returns**:\
`boolean` - Whether the ban was successful.

**Example**:

```lua
SentinelAPI:BanAsync(player, {
    Moderator = 12345,
    BanType = "Global",
    BanLengthType = "Permanent",
    PublicReason = "Violation of rules",
    PrivateReason = "Severe offense",
    BanUniversal = true,
})
```

***

#### 2. **OfflineBanAsync**

Bans a user by their UserId, even if they are offline.

**Signature**:

```lua
function OfflineBanAsync(UserId: number, BanConfig: types.BanConfig): boolean
```

**Parameters**:

* `UserId`: The Roblox UserId to ban.
* `BanConfig`: A table with ban details (see `BanConfig` type).

**Returns**:\
`boolean` - Whether the ban was successful.

***

#### 3. **BatchBanAsync**

Bans multiple players at once.

**Signature**:

```lua
function BatchBanAsync(PlayerList: {Player}, BanConfig: types.BanConfig): (boolean, number, number)
```

**Parameters**:

* `PlayerList`: A list of `Player` instances to ban.
* `BanConfig`: Ban configuration details.

**Returns**:

* `boolean`: Whether all bans were successful.
* `number`: Count of successful bans.
* `number`: Count of failed bans.

***

#### 4. **BatchOfflineBanAsync**

Bans multiple users by their UserIds.

**Signature**:

```lua
function BatchOfflineBanAsync(UserIds: {number}, BanConfig: types.BanConfig): (boolean, number, number)
```

**Parameters**:

* `UserIds`: List of UserIds to ban.
* `BanConfig`: Ban configuration details.

**Returns**:

* `boolean`: Whether all bans were successful.
* `number`: Count of successful bans.
* `number`: Count of failed bans.

***

#### 5. **UnbanAsync**

Unbans a user by their UserId.

**Signature**:

```lua
function UnbanAsync(UserId: number, Reason: string): boolean
```

**Parameters**:

* `UserId`: The UserId to unban.
* `Reason`: Reason for the unban.

**Returns**:\
`boolean` - Whether the unban was successful.

***

#### 6. **IsPlayerBanned**

Checks if a player is banned.

**Signature**:

```lua
function IsPlayerBanned(Player: Player): boolean
```

**Parameters**:

* `Player`: The `Player` instance to check.

**Returns**:\
`boolean` - Whether the player is banned.

***

#### 7. **IsUserIdBanned**

Checks if a UserId is banned.

**Signature**:

```lua
function IsUserIdBanned(UserId: number): boolean
```

**Parameters**:

* `UserId`: The UserId to check.

**Returns**:\
`boolean` - Whether the UserId is banned.

***

#### 8. **GetPendingBans**

Retrieves the list of pending bans.

**Signature**:

```lua
function GetPendingBans(): types.BanList?
```

**Returns**:

* `types.BanList?`: A list of pending bans or `nil` if an error occurs.

***

#### 9. **GetPendingUnbans**

Retrieves the list of pending unbans.

**Signature**:

```lua
function GetPendingUnbans(): types.BanList?
```

**Returns**:

* `types.BanList?`: A list of pending unbans or `nil` if an error occurs.

***

#### 10. **ProccessPendingBans**

Processes all pending bans and applies them.

**Signature**:

```lua
function ProccessPendingBans(): void
```

***

#### 11. **ProccessPendingUnbans**

Processes all pending unbans and applies them.

**Signature**:

```lua
function ProccessPendingUnbans(): void
```

***

#### 12. **ReplicateUpdatedBan**

Updates and replicates a ban.

**Signature**:

```lua
function ReplicateUpdatedBan(UserId: number, BanConfig: types.BanConfig): boolean
```

**Parameters**:

* `UserId`: The UserId to update the ban for.
* `BanConfig`: Updated ban configuration.

**Returns**:\
`boolean` - Whether the update was successful.

***

### Error Handling

Errors during API calls (e.g., HTTP requests) are logged with `warn` statements when `Config.DEBUG_INFO_ENABLED` is true. Developers should monitor the output for warnings if operations fail.

***

### Example Workflow

1. Ban a player temporarily:

   ```lua
   SentinelAPI:BanAsync(player, {
       Moderator = 12345,
       BanType = "Experience",
       BanLengthType = "Temporary",
       BanLength = "1d",
       PublicReason = "Spamming",
       PrivateReason = "Chat abuse",
       BanUniversal = false,
   })
   ```
2. Unban a player:

   ```lua
   SentinelAPI:UnbanAsync(12345678, "Appeal accepted.")
   ```
3. Process all pending bans:

   ```lua
   SentinelAPI:ProccessPendingBans()
   ```